diff --git a/glib/gmain.h b/glib/gmain.h index 14a1d2b06..13cbddf87 100644 --- a/glib/gmain.h +++ b/glib/gmain.h @@ -301,15 +301,101 @@ struct _GSourceCallbackFuncs */ typedef void (*GSourceDummyMarshal) (void); +/** + * GSourceFuncsPrepareFunc: + * @source: The #GSource + * @timeout_: (out) (optional): the maximum timeout (in milliseconds) which should be passed to the poll call + * + * Checks the source for readiness. + * + * Called before all the file descriptors are polled. If the + * source can determine that it is ready here (without waiting for the + * results of the poll call) it should return %TRUE. It can also return + * a @timeout_ value which should be the maximum timeout (in milliseconds) + * which should be passed to the poll call. The actual timeout used will + * be `-1` if all sources returned `-1`, or it will be the minimum of all + * the @timeout_ values returned which were greater than or equal to `0`. + * If the prepare function returns a timeout and the source also has a + * ready time set, then the lower of the two will be used. + * + * Since 2.36 this may be `NULL`, in which case the effect is as if the + * function always returns `FALSE` with a timeout of `-1`. + * + * Returns: %TRUE if the source is ready, %FALSE otherwise + * + * Since: 2.82 + */ +typedef gboolean (*GSourceFuncsPrepareFunc) (GSource *source, + gint *timeout_); + +/** + * GSourceFuncsCheckFunc: + * @source: The #GSource + * + * Checks if the source is ready to be dispatched. + * + * Called after all the file descriptors are polled. The source + * should return %TRUE if it is ready to be dispatched. Note that some + * time may have passed since the previous prepare function was called, + * so the source should be checked again here. + * + * Since 2.36 this may be `NULL`, in which case the effect is + * as if the function always returns `FALSE`. + * + * Returns: %TRUE if ready to be dispatched, %FALSE otherwise + * + * Since: 2.82 + */ +typedef gboolean (*GSourceFuncsCheckFunc) (GSource *source); + +/** + * GSourceFuncsDispatchFunc: + * @source: The #GSource + * @callback: (nullable): The #GSourceFunc to call + * @user_data: (nullable): data to pass to @callback + * + * Dispatches the source callback. + * + * Called to dispatch the event source, after it has returned + * `TRUE` in either its prepare or its check function, or if a ready time + * has been reached. The dispatch function receives a callback function and + * user data. The callback function may be `NULL` if the source was never + * connected to a callback using [method@GLib.Source.set_callback]. The dispatch + * function should call the callback function with @user_data and whatever + * additional parameters are needed for this type of event source. The + * return value of the dispatch function should be [const@GLib.SOURCE_REMOVE] + * if the source should be removed or [const@GLib.SOURCE_CONTINUE] to keep it. + * + * Returns: [const@GLib.SOURCE_REMOVE] if the source should be removed, + * [const@GLib.SOURCE_CONTINUE] otherwise. + * + * Since: 2.82 + */ +typedef gboolean (*GSourceFuncsDispatchFunc) (GSource *source, + GSourceFunc callback, + gpointer user_data); + +/** + * GSourceFuncsFinalizeFunc: + * @source: The #GSource + * + * Finalizes the source. + * + * Called when the source is finalized. At this point, the source + * will have been destroyed, had its callback cleared, and have been removed + * from its [type@GLib.MainContext], but it will still have its final reference + * count, so methods can be called on it from within this function. + * + * Since: 2.82 + */ +typedef void (*GSourceFuncsFinalizeFunc) (GSource *source); + struct _GSourceFuncs { - gboolean (*prepare) (GSource *source, - gint *timeout_);/* Can be NULL */ - gboolean (*check) (GSource *source);/* Can be NULL */ - gboolean (*dispatch) (GSource *source, - GSourceFunc callback, - gpointer user_data); - void (*finalize) (GSource *source); /* Can be NULL */ + GSourceFuncsPrepareFunc prepare; /* Can be NULL */ + GSourceFuncsCheckFunc check; /* Can be NULL */ + GSourceFuncsDispatchFunc dispatch; + GSourceFuncsFinalizeFunc finalize; /* Can be NULL */ /*< private >*/ /* For use by g_source_set_closure */