IrisScheduler

IrisScheduler — A generic, extendable scheduler for work items

Synopsis

#define             IRIS_SCHEDULER_CONST                (obj)
                    IrisScheduler;
IrisScheduler*      iris_scheduler_new                  (void);
IrisScheduler*      iris_scheduler_new_full             (guint min_threads,
                                                         guint max_threads);
IrisScheduler*      iris_scheduler_default              (void);
gint                iris_scheduler_get_min_threads      (IrisScheduler *scheduler);
gint                iris_scheduler_get_max_threads      (IrisScheduler *scheduler);
void                iris_scheduler_queue                (IrisScheduler *scheduler,
                                                         IrisCallback func,
                                                         gpointer data,
                                                         GDestroyNotify notify);
void                iris_scheduler_add_thread           (IrisScheduler *scheduler,
                                                         IrisThread *thread);
void                iris_scheduler_remove_thread        (IrisScheduler *scheduler,
                                                         IrisThread *thread);

Object Hierarchy

  GObject
   +----IrisScheduler
         +----IrisWSScheduler
         +----IrisLFScheduler

Description

IrisScheduler is a base class used for managing the scheduling of work items onto active threads. The default scheduler is sufficient for most purposes. However, if you need custom scheduling with different queuing decisions you can create your own.

The default scheduler will have a thread per-core with a minimum of 2 threads.

By default, a scheduler will be given "min-threads" threads during startup. If a "leader" thread, (typically the first thread added) feels it is getting behind, it will ask the scheduler manager for more help. The scheduler manager will try to first repurpose existing threads, or create new threads if no existing threads are available. Based on the speed of work performed by the scheduler, the manager will try to appropriate a sufficient number of threads.

Details

IRIS_SCHEDULER_CONST()

#define             IRIS_SCHEDULER_CONST(obj)

obj :

IrisScheduler

typedef struct _IrisScheduler IrisScheduler;

iris_scheduler_new ()

IrisScheduler*      iris_scheduler_new                  (void);

Creates a new instance of IrisScheduler with the defaults.

Returns :

the newly created IrisScheduler instance.

iris_scheduler_new_full ()

IrisScheduler*      iris_scheduler_new_full             (guint min_threads,
                                                         guint max_threads);

Creates a new scheduler with a defined set of thread ratios.

`min_threads` :	The minimum number of threads to allocate
`max_threads` :	The maximum number of threads to allocate
Returns :	the newly created scheduler instance.

iris_scheduler_default ()

IrisScheduler*      iris_scheduler_default              (void);

Retrieves the default scheduler which can be shared.

Returns :

a IrisScheduler instance

iris_scheduler_get_min_threads ()

gint                iris_scheduler_get_min_threads      (IrisScheduler *scheduler);

Requests the minimum number of threads that the scheduler needs to execute efficiently. This value should never change, and should always be greater or equal to 1.

`scheduler` :	An IrisScheduler
Returns :	the minimum number of threads to allocate to the scheduler.

iris_scheduler_get_max_threads ()

gint                iris_scheduler_get_max_threads      (IrisScheduler *scheduler);

Retrieves the maximum number of threads the scheduler should be allocated. The default is equal to the number of cpus unless there is only a single cpu, in which case the default is 2.

Currently, only Linux is supported for the number of cpus. If you would like another OS supported, please send an email with the method to retreive the number of cpus (get_nprocs() on Linux).

`scheduler` :	An IrisScheduler
Returns :	the maximum number of threads to allocate.

iris_scheduler_queue ()

void                iris_scheduler_queue                (IrisScheduler *scheduler,
                                                         IrisCallback func,
                                                         gpointer data,
                                                         GDestroyNotify notify);

NOTE: notify will probably disappear soon

Queues a new work item to be executed by one of the schedulers work threads.

`scheduler` :	An IrisScheduler
`func` :	An IrisCallback
`data` :	data for `func`
`notify` :	an optional callback after execution

iris_scheduler_add_thread ()

void                iris_scheduler_add_thread           (IrisScheduler *scheduler,
                                                         IrisThread *thread);

Requests that the scheduler add the thread to its set of executing threads. It is the responsibility of the scheduler to tell the thread to start managing a work queue with iris_thread_manage().

`scheduler` :	An IrisScheduler
`thread` :	An IrisThread

iris_scheduler_remove_thread ()

void                iris_scheduler_remove_thread        (IrisScheduler *scheduler,
                                                         IrisThread *thread);

Requests that a scheduler remove the thread from current activity. If the scheduler has a dedicated queue for the thread, it should flush the items into another threads or set of threads queues.

`scheduler` :	An IrisScheduler
`thread` :	An IrisThread