GSource: mark some API as "implementation only"

Clarify that _add_poll() _remove_poll() _add_unix_fd(),
_modify_unix_fd(), _remove_unix_fd(), _query_unix_fd(),
_set_ready_time(), _add_child_source() and _remove_child_source() are only
intended to be used by the implementation of a particular GSource -- not its
consumers.

https://bugzilla.gnome.org/show_bug.cgi?id=724707

1 files changed, 27 insertions, 0 deletions

diff --git a/glib/gmain.c b/glib/gmain.c
index a9ddabf9b..af39be19c 100644
--- a/glib/gmain.c
+++ b/glib/gmain.c
@@ -1335,6 +1335,9 @@ g_source_get_context (GSource *source)
  * the @revents field in the #GPollFD struct and return %TRUE if events need
  * to be processed.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * Using this API forces the linear scanning of event sources on each
  * main loop iteration.  Newly-written event sources should try to use
  * g_source_add_unix_fd() instead of this API.
@@ -1371,6 +1374,9 @@ g_source_add_poll (GSource *source,
  * 
  * Removes a file descriptor from the set of file descriptors polled for
  * this source. 
+ *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
  **/
 void
 g_source_remove_poll (GSource *source,
@@ -1417,6 +1423,9 @@ g_source_remove_poll (GSource *source,
  * @source will hold a reference on @child_source while @child_source
  * is attached to it.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * Since: 2.28
  **/
 void
@@ -1473,6 +1482,9 @@ g_child_source_remove_internal (GSource *child_source,
  *
  * Detaches @child_source from @source and destroys it.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * Since: 2.28
  **/
 void
@@ -1768,6 +1780,9 @@ g_source_get_priority (GSource *source)
  * for both sources is reached during the same main context iteration
  * then the order of dispatch is undefined.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * Since: 2.36
  **/
 void
@@ -2299,6 +2314,9 @@ g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
  * It is not necessary to remove the fd before destroying the source; it
  * will be cleaned up automatically.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * As the name suggests, this function is not available on Windows.
  *
  * Returns: an opaque tag
@@ -2351,6 +2369,9 @@ g_source_add_unix_fd (GSource      *source,
  * If you want to remove a fd, don't set its event mask to zero.
  * Instead, call g_source_remove_unix_fd().
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * As the name suggests, this function is not available on Windows.
  *
  * Since: 2.36
@@ -2386,6 +2407,9 @@ g_source_modify_unix_fd (GSource      *source,
  * watched while keeping the same source around.  In the normal case you
  * will just want to destroy the source.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * As the name suggests, this function is not available on Windows.
  *
  * Since: 2.36
@@ -2430,6 +2454,9 @@ g_source_remove_unix_fd (GSource  *source,
  * The return value of this function is only defined when the function
  * is called from the check or dispatch functions for @source.
  *
+ * This API is only intended to be used by implementations of #GSource.
+ * Do not call this API on a #GSource that you did not create.
+ *
  * As the name suggests, this function is not available on Windows.
  *
  * Returns: the conditions reported on the fd