3.10 The BeeSoft Scheduler’s API
RWI, Inc, supplies two versions of the Scheduler API (Application Program Interface). In the BeeSoft library, all debugging calls are disabled; they will simply be ignored if called. In the BeeSoftDebug library, all debugging calls are fully enabled. Select the version of the library you want to use at compile time. For examples, see the example makefiles in ~bee/src/examples.
3.10.1 BeeSoft Scheduler API - General Calls
void raiInit( ); -- Initializes the BeeSoft Scheduler before creating modules.
void raiStart( ); -- Begins scheduling events, after all modules have been created.
void raiShutdown( );
Forces invocation of shutdown callbacks for all modules and stops the BeeSoft Scheduler. After the shutdown callbacks for all modules are executed, the memory containing those modules is freed and can no longer be referenced.
void catchInterrupts( );
Specifies that the interrupt (<CTRL-C>) and all kill signals initiate a call to raiShutdown, thus shutting down all modules and stopping the BeeSoft Scheduler. The application program will then exit with a return value of zero.
raiModule* makeModule(char*name,void (*shutdown) (raiModule*) );
Creates a module with the required name and shutdown callback function. If there is no shutdown callback, pass NULL.
void addPolling ( raiModule* mod,void (*poll) (raiModule*), unsigned long poll_msecs);
Adds polling to an existing module. Pass the polling callback function, and the interval in milliseconds.
disablePolling (mod); -Turns off polling for the specified module.
enablePolling (mod); - Turns on polling for the specified module.
void addSelect ( raiModule* mod,void (*select) (raiModule*), char* filename);
Adds selection. Pass the callback function and the name of the file you want watched.
enable Select (raiModule* mod); - Turns on selection of the specified module.
disableSelect (raiModule* mod); - Turns off selection of the specified module.
void addTimeout (raiModule* mod, void (*timeout) (raiModule*), unsigned long timeout);
Adds a timeout. Pass the callback function, and the delay until the timeout shall occur. Once the timeout expires, the callback function is called exactly once. If you want further timeouts (or periodic timeouts), use resetTimeout or addTimeout.
disableTimeout (raiModule* mod); - Turns off the most recently scheduled timeout.
enableTimeout (raiModule* mod);
Turns on the most recently scheduled timeout. If the time period specified for a timeout has expired, and you call enableTimeout, that timeout will occur immediately. (If it has already been serviced once, the timeout will re-occur.)
void resetTimeout (raiModule* mod);
Postpones the current timeout, which will then occur at current time plus the delay interval specified in addTimeout. If the timeout was previously disabled, this call enables it.
3.10.2 BeeSoft Scheduler API - Utility Function Calls
unsigned long getRaiTime ( );
Returns the number of milliseconds since the function initRaiTime was last called.
void setRaiTime( ); -- Resets the BeeSoft Scheduler’s millisecond counter to zero.
void setErrorStream (FILE* file);
Specifies that BeeSoft error and informational messages are sent to the passed FILE* rather than to stderr. To prevent multiple error messages from being buffered by the filesystem, call setbuf(file,0) for your message file before calling setErrorStream.
3.10.3 BeeSoft Scheduler API - Time Structure Macros
For these calls, t1, t2 and t3 must be timeval structures as defined in sys/time.h. These macros are useful in understanding the internal workings of BeeSoft modules that store time in timeval structures.
time_greater (t1, t2); - Returns non-zero if t1 is greater than t2.
add_time (t1, t2, t3); - Sets t3 to the sum of t1 and t2, with appropriate carries.
subtract_time (t1, t2, t3);
Sets t3 to the difference of t1and t2 (t1 minus t2) with appropriate borrows.
print_time (file, t1);
Prints the seconds and microseconds of t1 on the passed FILE*.
msecsToUsecs (msecs, secs, usecs); - Converts milliseconds to microseconds.
Returns the number of milliseconds represented by a timeval. (Add 499 to the usec value to get the round-up. Otherwise, 800 usecs would contribute 0 ms to the milliseconds value msecs.)
printTimeAsMsecs (file, t);
Prints the number of seconds returned by timevalToMsecs in milliseconds. (Note: timevalToMsecs will overflow if you specify too large a timeval value (a time of about 48 days). For printing intervals, this is fine. However, for absolute time, the 48-day limit is overcome by using init_rai_time to set a "zero" timeval and subtracting this zero from any timeval used in this macro.)
reset_time (t1); - Sets the seconds and microseconds of t1 to zero.
null_time (t1); - Returns non-zero if the seconds and microseconds of t1 are both zero.
addInterval (begin, end, accum) { subtractTime (accum, begin, accum) ; \ addTime (accum, end, accum) ; }
Used in debugging to add the amount of time between two timevals to a third timeval. For example, it might add the time before and after a call, then add the elapsed time to the amount of time spent on the call to date.
