luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-28 08:26:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'gmain-cleanups' into 'main'

Browse Source 
GMainContext: Use nullable context in docs (and in some missing code)

See merge request GNOME/glib!3234
This commit is contained in:
Marco Trevisan 2023-01-27 14:03:13 +00:00
commit 183c646fea
1 changed files with 75 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
glib/gmain.c
View File

@ -567,7 +567,7 @@ GSourceFuncs g_idle_funcs =
/** /**
* g_main_context_ref: * g_main_context_ref:
* @context: a #GMainContext * @context: (not nullable): a #GMainContext
* *
* Increases the reference count on a #GMainContext object by one. * Increases the reference count on a #GMainContext object by one.
* *
@ -595,7 +595,7 @@ poll_rec_list_free (GMainContext *context,
/** /**
* g_main_context_unref: * g_main_context_unref:
* @context: a #GMainContext * @context: (not nullable): a #GMainContext
* *
* Decreases the reference count on a #GMainContext object by one. If * Decreases the reference count on a #GMainContext object by one. If
* the result is zero, free the context and free all associated memory. * the result is zero, free the context and free all associated memory.
@ -787,12 +787,12 @@ g_main_context_new_with_flags (GMainContextFlags flags)
/** /**
* g_main_context_default: * g_main_context_default:
* *
* Returns the global default main context. This is the main context * Returns the global-default main context. This is the main context
* used for main loop functions when a main loop is not explicitly * used for main loop functions when a main loop is not explicitly
* specified, and corresponds to the "main" main loop. See also * specified, and corresponds to the "main" main loop. See also
* g_main_context_get_thread_default(). * g_main_context_get_thread_default().
* *
* Returns: (transfer none): the global default main context. * Returns: (transfer none): the global-default main context.
**/ **/
GMainContext * GMainContext *
g_main_context_default (void) g_main_context_default (void)
@ -809,7 +809,7 @@ g_main_context_default (void)
#ifdef G_MAIN_POLL_DEBUG #ifdef G_MAIN_POLL_DEBUG
if (_g_main_poll_debug) if (_g_main_poll_debug)
g_print ("default context=%p\n", context); g_print ("global-default main context=%p\n", context);
#endif #endif
g_once_init_leave (&default_main_context, context); g_once_init_leave (&default_main_context, context);
@ -840,14 +840,15 @@ static GPrivate thread_context_stack = G_PRIVATE_INIT (free_context_stack);
/** /**
* g_main_context_push_thread_default: * g_main_context_push_thread_default:
* @context: (nullable): a #GMainContext, or %NULL for the global default context * @context: (nullable): a #GMainContext, or %NULL for the global-default
* main context
* *
* Acquires @context and sets it as the thread-default context for the * Acquires @context and sets it as the thread-default context for the
* current thread. This will cause certain asynchronous operations * current thread. This will cause certain asynchronous operations
* (such as most [gio][gio]-based I/O) which are * (such as most [gio][gio]-based I/O) which are
* started in this thread to run under @context and deliver their * started in this thread to run under @context and deliver their
* results to its main loop, rather than running under the global * results to its main loop, rather than running under the global
* default context in the main thread. Note that calling this function * default main context in the main thread. Note that calling this function
* changes the context returned by g_main_context_get_thread_default(), * changes the context returned by g_main_context_get_thread_default(),
* not the one returned by g_main_context_default(), so it does not affect * not the one returned by g_main_context_default(), so it does not affect
* the context used by functions like g_idle_add(). * the context used by functions like g_idle_add().
@ -911,7 +912,8 @@ g_main_context_push_thread_default (GMainContext *context)
/** /**
* g_main_context_pop_thread_default: * g_main_context_pop_thread_default:
* @context: (nullable): a #GMainContext object, or %NULL * @context: (nullable): a #GMainContext, or %NULL for the global-default
* main context
* *
* Pops @context off the thread-default context stack (verifying that * Pops @context off the thread-default context stack (verifying that
* it was on the top of the stack). * it was on the top of the stack).
@ -956,7 +958,7 @@ g_main_context_pop_thread_default (GMainContext *context)
* g_main_context_ref_thread_default() instead. * g_main_context_ref_thread_default() instead.
* *
* Returns: (transfer none) (nullable): the thread-default #GMainContext, or * Returns: (transfer none) (nullable): the thread-default #GMainContext, or
* %NULL if the thread-default context is the global default context. * %NULL if the thread-default context is the global-default main context.
* *
* Since: 2.22 * Since: 2.22
**/ **/
@ -979,7 +981,7 @@ g_main_context_get_thread_default (void)
* g_main_context_get_thread_default(), but also adds a reference to * g_main_context_get_thread_default(), but also adds a reference to
* it with g_main_context_ref(). In addition, unlike * it with g_main_context_ref(). In addition, unlike
* g_main_context_get_thread_default(), if the thread-default context * g_main_context_get_thread_default(), if the thread-default context
* is the global default context, this will return that #GMainContext * is the global-default context, this will return that #GMainContext
* (with a ref added to it) rather than returning %NULL. * (with a ref added to it) rather than returning %NULL.
* *
* Returns: (transfer full): the thread-default #GMainContext. Unref * Returns: (transfer full): the thread-default #GMainContext. Unref
@ -1336,7 +1338,8 @@ g_source_attach_unlocked (GSource *source,
/** /**
* g_source_attach: * g_source_attach:
* @source: a #GSource * @source: a #GSource
* @context: (nullable): a #GMainContext (if %NULL, the default context will be used) * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Adds a #GSource to a @context so that it will be executed within * Adds a #GSource to a @context so that it will be executed within
* that context. Remove it by calling g_source_destroy(). * that context. Remove it by calling g_source_destroy().
@ -2442,7 +2445,8 @@ g_source_unref (GSource *source)
/** /**
* g_main_context_find_source_by_id: * g_main_context_find_source_by_id:
* @context: (nullable): a #GMainContext (if %NULL, the default context will be used) * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @source_id: the source ID, as returned by g_source_get_id(). * @source_id: the source ID, as returned by g_source_get_id().
* *
* Finds a #GSource given a pair of context and ID. * Finds a #GSource given a pair of context and ID.
@ -2483,7 +2487,8 @@ g_main_context_find_source_by_id (GMainContext *context,
/** /**
* g_main_context_find_source_by_funcs_user_data: * g_main_context_find_source_by_funcs_user_data:
* @context: (nullable): a #GMainContext (if %NULL, the default context will be used). * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used).
* @funcs: the @source_funcs passed to g_source_new(). * @funcs: the @source_funcs passed to g_source_new().
* @user_data: the user data from the callback. * @user_data: the user data from the callback.
* *
@ -2533,7 +2538,8 @@ g_main_context_find_source_by_funcs_user_data (GMainContext *context,
/** /**
* g_main_context_find_source_by_user_data: * g_main_context_find_source_by_user_data:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @user_data: the user_data for the callback. * @user_data: the user_data for the callback.
* *
* Finds a source with the given user data for the callback. If * Finds a source with the given user data for the callback. If
@ -3493,7 +3499,8 @@ g_main_dispatch (GMainContext *context)
/** /**
* g_main_context_acquire: * g_main_context_acquire:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Tries to become the owner of the specified context. * Tries to become the owner of the specified context.
* If some other thread is the owner of the context, * If some other thread is the owner of the context,
@ -3505,6 +3512,9 @@ g_main_dispatch (GMainContext *context)
* You must be the owner of a context before you * You must be the owner of a context before you
* can call g_main_context_prepare(), g_main_context_query(), * can call g_main_context_prepare(), g_main_context_query(),
* g_main_context_check(), g_main_context_dispatch(). * g_main_context_check(), g_main_context_dispatch().
*
* Since 2.76 @context can be %NULL to use the global-default
* main context.
* *
* Returns: %TRUE if the operation succeeded, and * Returns: %TRUE if the operation succeeded, and
* this thread is now the owner of @context. * this thread is now the owner of @context.
@ -3544,7 +3554,8 @@ g_main_context_acquire (GMainContext *context)
/** /**
* g_main_context_release: * g_main_context_release:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Releases ownership of a context previously acquired by this thread * Releases ownership of a context previously acquired by this thread
* with g_main_context_acquire(). If the context was acquired multiple * with g_main_context_acquire(). If the context was acquired multiple
@ -3594,9 +3605,6 @@ g_main_context_wait_internal (GMainContext *context,
GThread *self = G_THREAD_SELF; GThread *self = G_THREAD_SELF;
gboolean loop_internal_waiter; gboolean loop_internal_waiter;
if (context == NULL)
context = g_main_context_default ();
loop_internal_waiter = (mutex == &context->mutex); loop_internal_waiter = (mutex == &context->mutex);
if (!loop_internal_waiter) if (!loop_internal_waiter)
@ -3640,7 +3648,8 @@ g_main_context_wait_internal (GMainContext *context,
/** /**
* g_main_context_wait: * g_main_context_wait:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @cond: a condition variable * @cond: a condition variable
* @mutex: a mutex, currently held * @mutex: a mutex, currently held
* *
@ -3679,7 +3688,8 @@ g_main_context_wait (GMainContext *context,
/** /**
* g_main_context_prepare: * g_main_context_prepare:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @priority: (out) (optional): location to store priority of highest priority * @priority: (out) (optional): location to store priority of highest priority
* source already ready. * source already ready.
* *
@ -3855,7 +3865,8 @@ g_main_context_prepare (GMainContext *context,
/** /**
* g_main_context_query: * g_main_context_query:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @max_priority: maximum priority source to check * @max_priority: maximum priority source to check
* @timeout_: (out): location to store timeout to be used in polling * @timeout_: (out): location to store timeout to be used in polling
* @fds: (out caller-allocates) (array length=n_fds): location to * @fds: (out caller-allocates) (array length=n_fds): location to
@ -3884,6 +3895,9 @@ g_main_context_query (GMainContext *context,
gint n_poll; gint n_poll;
GPollRec *pollrec, *lastpollrec; GPollRec *pollrec, *lastpollrec;
gushort events; gushort events;
if (context == NULL)
context = g_main_context_default ();
LOCK_CONTEXT (context); LOCK_CONTEXT (context);
@ -3950,7 +3964,8 @@ g_main_context_query (GMainContext *context,
/** /**
* g_main_context_check: * g_main_context_check:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @max_priority: the maximum numerical priority of sources to check * @max_priority: the maximum numerical priority of sources to check
* @fds: (array length=n_fds): array of #GPollFD's that was passed to * @fds: (array length=n_fds): array of #GPollFD's that was passed to
* the last call to g_main_context_query() * the last call to g_main_context_query()
@ -3964,6 +3979,9 @@ g_main_context_query (GMainContext *context,
* You must have successfully acquired the context with * You must have successfully acquired the context with
* g_main_context_acquire() before you may call this function. * g_main_context_acquire() before you may call this function.
* *
* Since 2.76 @context can be %NULL to use the global-default
* main context.
*
* Returns: %TRUE if some sources are ready to be dispatched. * Returns: %TRUE if some sources are ready to be dispatched.
**/ **/
gboolean gboolean
@ -3977,6 +3995,9 @@ g_main_context_check (GMainContext *context,
GPollRec *pollrec; GPollRec *pollrec;
gint n_ready = 0; gint n_ready = 0;
gint i; gint i;
if (context == NULL)
context = g_main_context_default ();
LOCK_CONTEXT (context); LOCK_CONTEXT (context);
@ -4153,16 +4174,23 @@ g_main_context_check (GMainContext *context,
/** /**
* g_main_context_dispatch: * g_main_context_dispatch:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Dispatches all pending sources. * Dispatches all pending sources.
* *
* You must have successfully acquired the context with * You must have successfully acquired the context with
* g_main_context_acquire() before you may call this function. * g_main_context_acquire() before you may call this function.
*
* Since 2.76 @context can be %NULL to use the global-default
* main context.
**/ **/
void void
g_main_context_dispatch (GMainContext *context) g_main_context_dispatch (GMainContext *context)
{ {
if (context == NULL)
context = g_main_context_default ();
LOCK_CONTEXT (context); LOCK_CONTEXT (context);
TRACE (GLIB_MAIN_CONTEXT_BEFORE_DISPATCH (context)); TRACE (GLIB_MAIN_CONTEXT_BEFORE_DISPATCH (context));
@ -4260,7 +4288,8 @@ g_main_context_iterate (GMainContext *context,
/** /**
* g_main_context_pending: * g_main_context_pending:
* @context: (nullable): a #GMainContext (if %NULL, the default context will be used) * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Checks if any sources have pending events for the given context. * Checks if any sources have pending events for the given context.
* *
@ -4283,7 +4312,8 @@ g_main_context_pending (GMainContext *context)
/** /**
* g_main_context_iteration: * g_main_context_iteration:
* @context: (nullable): a #GMainContext (if %NULL, the default context will be used) * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @may_block: whether the call may block. * @may_block: whether the call may block.
* *
* Runs a single iteration for the given main loop. This involves * Runs a single iteration for the given main loop. This involves
@ -4318,7 +4348,8 @@ g_main_context_iteration (GMainContext *context, gboolean may_block)
/** /**
* g_main_loop_new: * g_main_loop_new:
* @context: (nullable): a #GMainContext (if %NULL, the default context will be used). * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used).
* @is_running: set to %TRUE to indicate that the loop is running. This * @is_running: set to %TRUE to indicate that the loop is running. This
* is not very important since calling g_main_loop_run() will set this to * is not very important since calling g_main_loop_run() will set this to
* %TRUE anyway. * %TRUE anyway.
@ -4612,7 +4643,8 @@ g_main_context_poll (GMainContext *context,
/** /**
* g_main_context_add_poll: * g_main_context_add_poll:
* @context: (nullable): a #GMainContext (or %NULL for the default context) * @context: (nullable): a #GMainContext (or %NULL for the global-default
* main context)
* @fd: a #GPollFD structure holding information about a file * @fd: a #GPollFD structure holding information about a file
* descriptor to watch. * descriptor to watch.
* @priority: the priority for this file descriptor which should be * @priority: the priority for this file descriptor which should be
@ -4686,7 +4718,8 @@ g_main_context_add_poll_unlocked (GMainContext *context,
/** /**
* g_main_context_remove_poll: * g_main_context_remove_poll:
* @context:a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @fd: a #GPollFD descriptor previously added with g_main_context_add_poll() * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll()
* *
* Removes file descriptor from the set of file descriptors to be * Removes file descriptor from the set of file descriptors to be
@ -4808,7 +4841,8 @@ g_source_get_time (GSource *source)
/** /**
* g_main_context_set_poll_func: * g_main_context_set_poll_func:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* @func: the function to call to poll all file descriptors * @func: the function to call to poll all file descriptors
* *
* Sets the function to use to handle polling of file descriptors. It * Sets the function to use to handle polling of file descriptors. It
@ -4840,7 +4874,8 @@ g_main_context_set_poll_func (GMainContext *context,
/** /**
* g_main_context_get_poll_func: * g_main_context_get_poll_func:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Gets the poll function set by g_main_context_set_poll_func(). * Gets the poll function set by g_main_context_set_poll_func().
* *
@ -4865,7 +4900,8 @@ g_main_context_get_poll_func (GMainContext *context)
/** /**
* g_main_context_wakeup: * g_main_context_wakeup:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* If @context is currently blocking in g_main_context_iteration() * If @context is currently blocking in g_main_context_iteration()
* waiting for a source to become ready, cause it to stop blocking * waiting for a source to become ready, cause it to stop blocking
@ -4911,7 +4947,8 @@ g_main_context_wakeup (GMainContext *context)
/** /**
* g_main_context_is_owner: * g_main_context_is_owner:
* @context: a #GMainContext * @context: (nullable): a #GMainContext (if %NULL, the global-default
* main context will be used)
* *
* Determines whether this thread holds the (recursive) * Determines whether this thread holds the (recursive)
* ownership of this #GMainContext. This is useful to * ownership of this #GMainContext. This is useful to
@ -6300,14 +6337,15 @@ g_idle_remove_by_data (gpointer data)
/** /**
* g_main_context_invoke: * g_main_context_invoke:
* @context: (nullable): a #GMainContext, or %NULL * @context: (nullable): a #GMainContext, or %NULL for the global-default
* main context
* @function: function to call * @function: function to call
* @data: data to pass to @function * @data: data to pass to @function
* *
* Invokes a function in such a way that @context is owned during the * Invokes a function in such a way that @context is owned during the
* invocation of @function. * invocation of @function.
* *
* If @context is %NULL then the global default main context — as * If @context is %NULL then the global-default main context — as
* returned by g_main_context_default() — is used. * returned by g_main_context_default() — is used.
* *
* If @context is owned by the current thread, @function is called * If @context is owned by the current thread, @function is called
@ -6340,7 +6378,8 @@ g_main_context_invoke (GMainContext *context,
/** /**
* g_main_context_invoke_full: * g_main_context_invoke_full:
* @context: (nullable): a #GMainContext, or %NULL * @context: (nullable): a #GMainContext, or %NULL for the global-default
* main context
* @priority: the priority at which to run @function * @priority: the priority at which to run @function
* @function: function to call * @function: function to call
* @data: data to pass to @function * @data: data to pass to @function