CrystalSpace

Public API Reference

csSchedule Class Reference

The csSchedule class provides an easy way to get timers in applications. More...

#include <csutil/schedule.h>

List of all members.

Public Member Functions

void AddCallback (void(*func)(void *), void *arg, int delay)
 Add a single-shot callback the function must be of type: void function(void *arg) arg is passed as argument to the function.
void AddRepeatCallback (void(*func)(void *), void *arg, int period)
 Add a repeating callback the function must be of type: void function(void *arg) arg is passed as argument to the function.
 csSchedule ()
 create an empty schedule
void RemoveCallback (void *arg)
 Remove a single-shot or repeating callback.
void RemoveCallback (void(*func)(void *), void *arg)
 Remove a single-shot callback.
void RemoveCallback (void(*func)(void *), void *arg, int period)
 Remove a repeating callback.
void TimePassed (int elapsed_time)
 Notify the schedule that time has passed, elapsed_time is in msec.


Detailed Description

The csSchedule class provides an easy way to get timers in applications.

It can handle both repeating and single-shot callbacks. It is useful for handling time in 3D virtual worlds.

Use it like this:

 class myEntity 
 {
   public:
   virtual void Update();
 };

Suppose you have an object of class myEntity, which looks like a button in your virtual world, and you want the button to blink. Calling Update every NextFrame would look bad, and handling the timing yourself is a hassle (and can be lots slower then mass-handling by csSchedule). So you can use the csSchedule to call the myEntity::Update method every second.

You can do it this way:

 void call_entity_update(void *arg)
 {
   myEntity *mp = (myEntity*)arg;
   mp->Update();
 }

You would then use the csSchedule method AddCallback(call_entity_update, (void*)my_entity, 1000); to have it call the function with the object pointer as argument after 1000 milliseconds (= 1 second) once. or you can use: AddRepeatCallback(call_entity_update, (void*)my_entity, 1000); to have the function called repeatedly, every 1000 msec (= second).

To notify the schedule that time has passed, each frame, for example in the NextFrame() method, you must call the TimePassed(elapsed_time) function.

This class is useful for callbacks in 3D virtual worlds, but the callbacks can have some jitter due to framerates. For mission-critical hardware IO calls (like controlling a floppy drive or controlling the UART) this jitter will be too big. In those cases use interrupt-driven callbacks, and place the controlling code in some platform-specific implementation file, since this type of use is typically platform-dependent. However, although this class cannot give callbacks inside a single frame, it will behave as best as possible using callbacks every frame.

Definition at line 81 of file schedule.h.


Constructor & Destructor Documentation

csSchedule::csSchedule (  ) 

create an empty schedule


Member Function Documentation

void csSchedule::AddCallback ( void(*)(void *)  func,
void *  arg,
int  delay 
)

Add a single-shot callback the function must be of type: void function(void *arg) arg is passed as argument to the function.

delay: the function is called this many msec have passed.

void csSchedule::AddRepeatCallback ( void(*)(void *)  func,
void *  arg,
int  period 
)

Add a repeating callback the function must be of type: void function(void *arg) arg is passed as argument to the function.

period: the function is called every time this many msec pass.

void csSchedule::RemoveCallback ( void *  arg  ) 

Remove a single-shot or repeating callback.

(if multiple identical calls exist, all are removed) removes all callbacks using given argument, whatever their function or period. Useful if the argument in question is an object that is destructed. So, in a class myEntity, in ~myEntity() you can call: schedule->RemoveCallback(this);

void csSchedule::RemoveCallback ( void(*)(void *)  func,
void *  arg 
)

Remove a single-shot callback.

(if multiple identical calls exist, the first is removed)

void csSchedule::RemoveCallback ( void(*)(void *)  func,
void *  arg,
int  period 
)

Remove a repeating callback.

(if multiple identical calls exist, the first is removed)

void csSchedule::TimePassed ( int  elapsed_time  ) 

Notify the schedule that time has passed, elapsed_time is in msec.

It will update the internal data and call any callbacks if necessary.


The documentation for this class was generated from the following file:
Generated for Crystal Space by doxygen 1.4.7