Merge branch 'typed-callbacks-gsourcefuncs' into 'main'

gmain: Refactor GSourceFuncs into typed callbacks

Closes #2765

See merge request GNOME/glib!4139

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,
+  GSourceFuncsPrepareFunc prepare; /* Can be NULL */
-                        gint       *timeout_);/* Can be NULL */
+  GSourceFuncsCheckFunc check;     /* Can be NULL */
-  gboolean (*check)    (GSource    *source);/* Can be NULL */
+  GSourceFuncsDispatchFunc dispatch;
-  gboolean (*dispatch) (GSource    *source,
+  GSourceFuncsFinalizeFunc finalize; /* Can be NULL */
-                        GSourceFunc callback,
-                        gpointer    user_data);
-  void     (*finalize) (GSource    *source); /* Can be NULL */
 
   /*< private >*/
   /* For use by g_source_set_closure */