NAME
OTC_Dispatcher -
Dispatcher of jobs.
SYNOPSIS
#include <OTC/dispatch/dispatch.hh>
class OTC_Dispatcher
{
public:
friend class OTC_DispatcherDummy;
static void initialise();
static int run();
inline static void stop();
inline OTC_Boolean isRunning() const;
static void schedule(OTC_Job* theJob);
static void initialise(OTC_JobQueue* theJobQueue);
static OTC_JobQueue* queue();
};
CLASS TYPE
Static
DESCRIPTION
OTC_Dispatcher is the collection point for jobs to be executed.
To schedule jobs, you should use the schedule() function. When
you run the dispatcher by calling run(), it will continually
poll the job queue for the next available job, execute the job
and then destroy it. When the job queue returns that there are no
more jobs, the dispatcher will return from run(). The dispatcher
will also return from the run() routine, if stopped prematurely
as a result of the stop() function being called.
The default job queue adds new jobs to the end of the queue, and
returns jobs for execution from the front of the queue. If you
require a more sophisticated queueing mechanism, you will need
to derive a new queue from OTC_JobQueue and pass it to the
dispatcher when you call initialise(), before queueing any jobs.
Even if you do not supply your own job queue, you must still call
initialise before and jobs are queued. An example of a more
sophisticated job queue would be one that, when returning the next
job would first check to see if any signals had occurred. If a
signal had occurred, it would return a job for the delivery of an
event corresponding to that signal, rather than returning the job
at the head of the queue. The same queue could also use system
select() or poll() function, to try and generate new jobs
corresponding to I/O and timer events.
INITIALISATION
static void initialise();
Initialises the dispatcher to use a
standard job queue. The dispatcher
must be initialised before any jobs
are scheduled.
EXECUTION
static int run();
Executes any jobs which have been
scheduled, until there are no more jobs to
run, or the dispatcher is stopped through
a call to stop(). If the dispatcher
runs out of jobs, then 0 is returned.
If the dispatcher is stopped, then -1
is returned.
inline static void stop();
Will cause run() to return to the
caller, even if there are still jobs
to be executed.
inline OTC_Boolean isRunning() const;
Returns OTCLIB_TRUE if the dispatcher
is currently running, otherwise returns
OTCLIB_FALSE. A value of OTCLIB_FALSE
is also returned if the dispatcher has
been stopped, but the run() routine
has not yet returned.
SCHEDULING
static void schedule(OTC_Job* theJob);
Add theJob to the queue of jobs to
be executed.
JOB QUEUE
static void initialise(OTC_JobQueue* theJobQueue);
Must be called before any jobs are queued
with the dispatcher. You may supply an
alternative job queue using the
theJobQueue argument. It is by defining
your own derived version of OTC_JobQueue
that you can modify the scheduling
algorithm. If this function is called
more than once, an exceptions is raised.
static OTC_JobQueue* queue();
Returns a pointer to the job queue.
If the dispatcher has not yet been
initialised, then 0 is returned.
SEE ALSO
OTC_JobQueue, OTC_Job
LIBRARY
OTC
AUTHOR(S)
Graham Dumpleton
COPYRIGHT
Copyright 1993 OTC LIMITED
Copyright 1994 DUMPLETON SOFTWARE CONSULTING PTY LIMITED