GPeriodic

GPeriodic — a periodic event clock

Synopsis

                    GPeriodic;

GPeriodic *              g_periodic_new                 (guint hz,
                                                         gint high_priority,
                                                         gint low_priority);
guint               g_periodic_get_hz                   (GPeriodic *periodic);
gint                g_periodic_get_high_priority        (GPeriodic *periodic);
gint                g_periodic_get_low_priority         (GPeriodic *periodic);

void                (*GPeriodicTickFunc)                (GPeriodic *periodic,
                                                         gint64 timestamp,
                                                         gpointer user_data);
guint               g_periodic_add                      (GPeriodic *periodic,
                                                         GPeriodicTickFunc callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
void                g_periodic_remove                   (GPeriodic *periodic,
                                                         guint tag);

void                g_periodic_block                    (GPeriodic *periodic);
void                g_periodic_unblock                  (GPeriodic *periodic,
                                                         gint64 unblock_time);

void                g_periodic_damaged                  (GPeriodic *periodic);

Object Hierarchy

  GObject
   +----GPeriodic

Properties

  "high-priority"            gint                  : Read / Write / Construct Only
  "hz"                       guint                 : Read / Write / Construct Only
  "low-priority"             gint                  : Read / Write / Construct Only

Signals

  "repair"                                         : Run Last
  "tick"                                           : Run Last

Description

GPeriodic is a periodic event clock that fires a configurable number of times per second and is capable of being put into synch with an external time source.

A number of GPeriodicTickFuncs are registered with g_periodic_add() and are called each time the clock "ticks".

The tick functions can report "damage" (ie: updates that need to be performed) that are handled in a "repair" phase that follows all the tick functions having been run. It is also possible to report damage while the clock is not running, in which case the rate of repairs will be rate limited as if the clock were running.

GPeriodic has a configurable priority range consisting of a high and low value. Other sources with a priority higher than the high value might starve GPeriodic and sources with the priority lower than the low value may be starved by GPeriodic.

GPeriodic will engage in dynamic scheduling with respect to sources that have their priorities within the high to low range. A given GPeriodic will ensure that the events dispatched from itself are generally using less than 50% of the CPU (on average) if other tasks are pending. If no other sources within the range are pending then GPeriodic will use up to all of the available CPU (which can lead to starvation of lower-priority sources, as mentioned above). The 50% figure is entirely arbitrary and may change or become configurable in the future.

For example, if a GPeriodic has been set to run at 10Hz and a particular iteration uses 140ms of time, then 2 ticks will be "skipped" to give other sources a chance to run (ie: the next tick will occur 300ms later rather than 100ms later, giving 160ms of time for other sources).

This means that the high priority value for GPeriodic should be set quite high (above anything else) and the low priority value for GPeriodic should be set lower than everything except true "idle" handlers (ie: things that you want to run only when the program is truly idle).

GPeriodic generally assumes that although the things attached to it may be poorly behaved in terms of non-yielding behaviour (either individually or in aggregate), the other sources on the main loop should be "well behaved". Other sources should try not to block the CPU for a substantial portion of the periodic interval.

The sources attached to a GPeriodic are permitted to be somewhat less well-behaved because they are generally rendering the UI for the user (which should be done smoothly) and also because they will be throttled by GPeriodic.

GPeriodic is intended to be used as a paint clock for managing geometry updates and painting of windows.

Details

GPeriodic

typedef struct _GPeriodic GPeriodic;

GPeriodic is an opaque structure type.

Since 2.28


g_periodic_new ()

GPeriodic *              g_periodic_new                 (guint hz,
                                                         gint high_priority,
                                                         gint low_priority);

Creates a new GPeriodic clock.

The created clock is attached to the thread-default main context in effect at the time of the call to this function. See g_main_context_push_thread_default() for more information.

Due to the fact that GMainContext is only accurate to the nearest millisecond, the frequency can not meaningfully get too close to 1000. For this reason, it is arbitrarily bounded at 120.

hz :

the frequency of the new clock in Hz (between 1 and 120)

Returns :

a new GPeriodic

Since 2.28


g_periodic_get_hz ()

guint               g_periodic_get_hz                   (GPeriodic *periodic);

Gets the frequency of the clock.

periodic :

a GPeriodic clock

Returns :

the frquency of the clock, in Hz

Since 2.28


g_periodic_get_high_priority ()

gint                g_periodic_get_high_priority        (GPeriodic *periodic);

Gets the GSource priority of the clock.

periodic :

a GPeriodic clock

Returns :

the high priority level

Since 2.28


g_periodic_get_low_priority ()

gint                g_periodic_get_low_priority         (GPeriodic *periodic);

Gets the priority level that GPeriodic uses to check for mainloop inactivity. Other sources scheduled below this level of priority are effectively ignored by GPeriodic and may be starved.

periodic :

a GPeriodic clock

Returns :

the low priority level

Since 2.28


GPeriodicTickFunc ()

void                (*GPeriodicTickFunc)                (GPeriodic *periodic,
                                                         gint64 timestamp,
                                                         gpointer user_data);

The signature of the callback function that is called when the GPeriodic clock ticks.

The timestamp parameter is equal for all callbacks called during a particular tick on a given clock.

periodic :

the GPeriodic clock that is ticking

timestamp :

the timestamp at the time of the tick

user_data :

the user data given to g_periodic_add()

Since 2.28


g_periodic_add ()

guint               g_periodic_add                      (GPeriodic *periodic,
                                                         GPeriodicTickFunc callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Request periodic calls to callback to start. The periodicity of the calls is determined by the 'hz' property.

This function may not be called from a handler of the repair signal, but it is perfectly reasonable to call it from a handler of the tick signal.

The callback may be cancelled later by using g_periodic_remove() on the return value of this function.

periodic :

a GPeriodic clock

callback :

a GPeriodicTickFunc function

user_data :

data for callback

notify :

for freeing user_data when it is no longer needed

Returns :

a non-zero tag identifying this callback

Since 2.28


g_periodic_remove ()

void                g_periodic_remove                   (GPeriodic *periodic,
                                                         guint tag);

Reverse the effect of a previous call to g_periodic_start().

tag is the ID returned by that function.

This function may not be called from a handler of the repair signal, but it is perfectly reasonable to call it from a handler of the tick signal.

periodic :

a GPeriodic clock

tag :

the ID of the callback to remove

Since 2.28


g_periodic_block ()

void                g_periodic_block                    (GPeriodic *periodic);

Temporarily blocks periodic from running in order to bring it in synch with an external time source.

This function must be called from a handler of the "repair" signal.

If this function is called, emission of the tick signal will be suspended until g_periodic_unblock() is called an equal number of times. Once that happens, the "tick" signal will run immediately and future "tick" signals will be emitted relative to the time at which the last call to g_periodic_unblock() occured.

periodic :

a GPeriodic clock

Since 2.28


g_periodic_unblock ()

void                g_periodic_unblock                  (GPeriodic *periodic,
                                                         gint64 unblock_time);

Reverses the effect of a previous call to g_periodic_block().

If this call removes the last block, the tick signal is immediately run. The repair signal may also be run if the clock is marked as damaged.

unblock_time is the monotonic time, as per g_get_monotonic_time(), at which the event causing the unblock occured.

This function may not be called from handlers of any signal emitted by periodic.

periodic :

a GPeriodic clock

unblock_time :

the unblock time

Since 2.28


g_periodic_damaged ()

void                g_periodic_damaged                  (GPeriodic *periodic);

Report damage and schedule the "repair" signal to be emitted during the next repair phase.

You may not call this function during the repair phase.

periodic :

a GPeriodic clock

Since 2.28

Property Details

The "high-priority" property

  "high-priority"            gint                  : Read / Write / Construct Only

the GSource priority level to run at.

Default value: 0


The "hz" property

  "hz"                       guint                 : Read / Write / Construct Only

rate (in Hz) at which the 'tick' signal is emitted.

Allowed values: [1,120]

Default value: 1


The "low-priority" property

  "low-priority"             gint                  : Read / Write / Construct Only

ignore tasks below this priority level.

Default value: 0

Signal Details

The "repair" signal

void                user_function                      (GPeriodic *gperiodic,
                                                        gpointer   user_data)      : Run Last

gperiodic :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "tick" signal

void                user_function                      (GPeriodic *gperiodic,
                                                        gint64     arg1,
                                                        gpointer   user_data)      : Run Last

gperiodic :

the object which received the signal.

user_data :

user data set when the signal handler was connected.