GPeriodic

GPeriodic — a periodic event clock

Synopsis

                    GPeriodic;

GPeriodic *         g_periodic_new                      (guint hz,
                                                         gint priority);
guint               g_periodic_get_hz                   (GPeriodic *periodic);
gint                g_periodic_get_priority             (GPeriodic *periodic);

void                (*GPeriodicTickFunc)                (GPeriodic *periodic,
                                                         guint64 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,
                                                         const GTimeSpec *unblock_time);

void                (*GPeriodicRepairFunc)              (GPeriodic *periodic,
                                                         gpointer user_data);
void                g_periodic_damaged                  (GPeriodic *periodic,
                                                         GPeriodicRepairFunc callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Object Hierarchy

  GObject
   +----GPeriodic

Properties

  "hz"                       guint                 : Read / Write / Construct Only
  "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 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 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)

priority :

the GSource priority to run at

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_priority ()

gint                g_periodic_get_priority             (GPeriodic *periodic);

Gets the GSource priority of the clock.

periodic :

a GPeriodic clock

Returns :

the priority level

Since 2.28


GPeriodicTickFunc ()

void                (*GPeriodicTickFunc)                (GPeriodic *periodic,
                                                         guint64 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,
                                                         const GTimeSpec *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. If it is NULL then g_get_monotonic_time() is called internally.

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

periodic :

a GPeriodic clock

unblock_time :

the unblock time, or NULL

Since 2.28


GPeriodicRepairFunc ()

void                (*GPeriodicRepairFunc)              (GPeriodic *periodic,
                                                         gpointer user_data);

The signature of the callback function that is called during the repair phase when damaged was reported using g_periodic_damaged().

periodic :

the GPeriodic clock that the damage was reported to

user_data :

the user data given to g_periodic_damaged()

Since 2.28


g_periodic_damaged ()

void                g_periodic_damaged                  (GPeriodic *periodic,
                                                         GPeriodicRepairFunc callback,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);

Report damage and schedule callback to be called during the next repair phase. Multiple registrations result in multiple invocations, so you should track for yourself if you are already registered.

You may not call this function during the repair phase.

periodic :

a GPeriodic clock

callback :

a GPeriodicRepairFunc

user_data :

data for callback

notify :

for freeing user_data when it is no longer needed

Since 2.28

Property Details

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 "priority" property

  "priority"                 gint                  : Read / Write / Construct Only

the GSource priority level to run at.

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,
                                                        guint64    arg1,
                                                        gpointer   user_data)      : Run Last

gperiodic :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.