The agentidler Library

agentidler is an Objective-C source file that provides a set of functions that tell whether or not your Xgrid agent program should stop using processor power due to a person walking up to the computer. It was written because Xgrid does not currently support forcibly terminating or suspending an agent program when the agent computer becomes unavailable. On the other hand, all the information you need to figure this out exists right at your fingertips on the agent machine. This library reduces all the logic and error checking involved with this idea down to a handful of simple, fast functions.

This code also provides some of the command strings for an Xgrid controller so that you don't have to memorize them yourself. These commands provide functions such as reporting progress to the controller, restarting the task or job, and declaring an agent unusable for the task or job. All you have to do is print the strings to stdout.

This code should compile on any platform, however the majority of the functionality exists only on Mac OS X.

agentidler download (revision 18)

Other attributes:

  • Programmer: Andrew Keller
  • License: BSD
  • Status: Stable, support available on OS X
  • Support Contact: Andrew Keller

Some of the functionality in the agentidler library was best achieved using Objective-C code, but I feel that it is important that the agentidler library be implementable from ANSI C, and thus, most of C's derivatives. With this in mind, the library itself is technically Objective C, however all of the public functions use ANSI C syntax - And thus, this library can be used with C, and most of C's derivatives.


This library provides three primary functions (plus some others, but these are the three most useful):

  • Getting machine idle status
  • Acting on machine idle status
    • One version for the static task distribution model
    • Another version for the dynamic task distribution model

These ideas correspond with the following functions:

  • int XGIdlerGetMachineIdleStatus( int smart )
  • int XGIdlerSleepUntilIdle( int smart )
  • int XGIdlerAgentAppShouldQuit( int maxRunTime, int smart )

Then, it is just a matter of using these functions. Typically, you would only use one of these. Just stick it in a place in your code where you do a lot of computing, and this library does the rest.

Explanations of exactly what these functions do, and a detailed example of how to use them is included with the agentidler library.

Extra Goodies

Because the agentidler library is designed for use with Xgrid agent programs, it makes some sense to include some other related useful functions.

  • Xgrid controller command strings
    String constants that you print to stdout that are used to report progress to the controller, restart the task or job, or declaring an agent unusable for the task or job.
  • Reporting progress to the controller
    A function that implements the above command string for reporting progress, and features the ability to not print if the value hasn't changed enough or if too little time has passed.

Other Platforms

Because a cross platform Xgrid agent daemon has been written, I feel that it is important to maintain this library with multi-platform functionality in mind. So far, however, the cross platform functionality of this code is restricted to only compiling on any platform. For example, if you compile this library on BSD or Linux, then the function XGIdlerGetMachineIdleStatus will always report that the machine is idle.

With that said, two of the functions here rely solely on the standard C library, and are completely cross platform because of that: XGIdlerGetElapsedSeconds, and XGIdlerReportProgressToController. And don't forget about the controller command strings. They'll work on any platform, too - they're just preprocessor defines.

BUT - If anyone has any code that would get this library to really run on other platforms, then I would be happy to include it in here!