Creating new source types
创建新的源类型

One of the unusual features of the GMainLoop functionality is that new types of event source can be created and used in addition to the builtin type of event source. A new event source type is used for handling GDK events. A new source type is created by "deriving" from the GSource structure. The derived type of source is represented by a structure that has the GSource structure as a first element, and other elements specific to the new source type. To create an instance of the new source type, call g_source_new() passing in the size of the derived structure and a table of functions. These GSourceFuncs determine the behavior of the new source type.
GMainLoop功能的不寻常功能之一是，除了内置类型的事件源之外，还可以创建和使用新类型的事件源。新的事件源类型用于处理 GDK 事件。通过从GSource结构“派生”来创建新的源类型。源的派生类型由一个结构表示，该结构将GSource结构作为第一个元素，以及特定于新源类型的其他元素。要创建新源类型的实例，请调用g_source_new()并传入派生结构的大小和函数表。这些GSourceFunc确定新源类型的行为。

New source types basically interact with the main context in two ways. Their prepare function in GSourceFuncs can set a timeout to determine the maximum amount of time that the main loop will sleep before checking the source again. In addition, or as well, the source can add file descriptors to the set that the main context checks using g_source_add_poll().
新的源类型基本上以两种方式与主上下文交互。 GSourceFuncs中的准备函数可以设置超时，以确定主循环在再次检查源之前休眠的最长时间。此外，源还可以将文件描述符添加到主上下文使用g_source_add_poll()检查的集合中。

Customizing the main loop iteration
自定义主循环迭代

Single iterations of a GMainContext can be run with g_main_context_iteration(). In some cases, more detailed control of exactly how the details of the main loop work is desired, for instance, when integrating the GMainLoop with an external main loop. In such cases, you can call the component functions of g_main_context_iteration() directly. These functions are g_main_context_prepare(), g_main_context_query(), g_main_context_check() and g_main_context_dispatch().
GMainContext的单次迭代可以使用g_main_context_iteration()运行。在某些情况下，需要对主循环的工作细节进行更详细的控制，例如，将GMainLoop与外部主循环集成时。在这种情况下，您可以直接调用g_main_context_iteration()的组件函数。这些函数是g_main_context_prepare() 、 g_main_context_query() 、 g_main_context_check()和g_main_context_dispatch() 。

If the event loop thread releases GMainContext ownership until the results required by g_main_context_check() are ready you must create a context with the flag G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING or else you'll lose g_source_attach() notifications. This happens for instance when you integrate the GLib event loop into implementations that follow the proactor pattern (i.e. in these contexts the poll() implementation will reclaim the thread for other tasks until the results are ready). One example of the proactor pattern is the Boost.Asio library.
如果事件循环线程释放GMainContext所有权，直到g_main_context_check()所需的结果准备就绪，则必须使用标志创建一个上下文 G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING 否则您将丢失g_source_attach()通知。例如，当您将 GLib 事件循环集成到遵循前摄器模式的实现中时，就会发生这种情况（即，在这些上下文中， poll()实现将回收其他任务的线程，直到结果准备就绪）。前摄器模式的一个示例是 Boost.Asio 库。

State of a Main Context
主要上下文的状态

The operation of these functions can best be seen in terms of a state diagram, as shown in this image.
这些函数的操作可以通过状态图来最好地了解，如下图所示。

On UNIX, the GLib mainloop is incompatible with fork(). Any program using the mainloop must either exec() or exit() from the child without returning to the mainloop.
在 UNIX 上，GLib 主循环与fork()不兼容。任何使用主循环的程序都必须从子循环中执行exec()或exit()而不返回到主循环。

Memory management of sources
源的内存管理

There are two options for memory management of the user data passed to a GSource to be passed to its callback on invocation. This data is provided in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and more generally, using g_source_set_callback(). This data is typically an object which ‘owns’ the timeout or idle callback, such as a widget or a network protocol implementation. In many cases, it is an error for the callback to be invoked after this owning object has been destroyed, as that results in use of freed memory.
对于传递给GSource的用户数据进行内存管理有两个选项，以便在调用时传递给其回调。此数据在对g_timeout_add() 、 g_timeout_add_full() 、 g_idle_add()等的调用中提供，更一般地，使用g_source_set_callback()提供。该数据通常是“拥有”超时或空闲回调的对象，例如小部件或网络协议实现。在许多情况下，在拥有的对象被销毁后调用回调是错误的，因为这会导致使用已释放的内存。

The first, and preferred, option is to store the source ID returned by functions such as g_timeout_add() or g_source_attach(), and explicitly remove that source from the main context using g_source_remove() when the owning object is finalized. This ensures that the callback can only be invoked while the object is still alive.
第一个也是首选选项是存储g_timeout_add()或g_source_attach()等函数返回的源 I​​D，并在所属对象完成时使用g_source_remove()从主上下文中显式删除该源。这确保了只能在对象仍然存在时调用回调。

The second option is to hold a strong reference to the object in the callback, and to release it in the callback’s GDestroyNotify. This ensures that the object is kept alive until after the source is finalized, which is guaranteed to be after it is invoked for the final time. The GDestroyNotify is another callback passed to the ‘full’ variants of GSource functions (for example, g_timeout_add_full()). It is called when the source is finalized, and is designed for releasing references like this.
第二个选项是在回调中保留对对象的强引用，并在回调的GDestroyNotify中释放它。这确保了对象在源完成之前一直保持活动状态，这保证是在最后一次调用它之后。 GDestroyNotify是传递给GSource函数的“完整”变体的另一个回调（例如， g_timeout_add_full() ）。它在源代码最终确定时被调用，旨在释放此类引用。

One important caveat of this second approach is that it will keep the object alive indefinitely if the main loop is stopped before the GSource is invoked, which may be undesirable.
第二种方法的一个重要警告是，如果在调用GSource之前停止主循环，它将使对象无限期地保持活动状态，这可能是不可取的。

g_main_loop_new () g_main_loop_new()

GMainLoop *
g_main_loop_new (GMainContext *context,
                 gboolean is_running);

Creates a new GMainLoop structure.
创建一个新的GMainLoop结构。

g_main_loop_ref ()

GMainLoop *
g_main_loop_ref (GMainLoop *loop);

Increases the reference count on a GMainLoop object by one.
将GMainLoop对象的引用计数增加一。

g_main_loop_unref ()

void
g_main_loop_unref (GMainLoop *loop);

Decreases the reference count on a GMainLoop object by one. If the result is zero, free the loop and free all associated memory.
将GMainLoop对象的引用计数减一。如果结果为零，则释放循环并释放所有关联的内存。

g_main_loop_run () g_main_loop_run()

void
g_main_loop_run (GMainLoop *loop);

Runs a main loop until g_main_loop_quit() is called on the loop. If this is called for the thread of the loop's GMainContext, it will process events from the loop, otherwise it will simply wait.
运行主循环，直到在循环中调用g_main_loop_quit() 。如果为循环的GMainContext线程调用此方法，它将处理循环中的事件，否则它将简单地等待。

g_main_loop_quit () g_main_loop_quit()

void
g_main_loop_quit (GMainLoop *loop);

Stops a GMainLoop from running. Any calls to g_main_loop_run() for the loop will return.
停止GMainLoop的运行。任何对循环的g_main_loop_run()调用都将返回。

Note that sources that have already been dispatched when g_main_loop_quit() is called will still be executed.
请注意，调用g_main_loop_quit()时已分派的源仍将被执行。

g_main_loop_is_running ()
g_main_loop_is_running()

gboolean
g_main_loop_is_running (GMainLoop *loop);

Checks to see if the main loop is currently being run via g_main_loop_run().
检查主循环当前是否正在通过g_main_loop_run()运行。

g_main_loop_get_context ()
g_main_loop_get_context()

GMainContext *
g_main_loop_get_context (GMainLoop *loop);

Returns the GMainContext of loop .
返回loop的GMainContext 。

g_main_new()

#define             g_main_new(is_running)

Creates a new GMainLoop for th default main context.
为默认主上下文创建一个新的GMainLoop 。

g_main_destroy()

#define             g_main_destroy(loop)

Frees the memory allocated for the GMainLoop.
释放为GMainLoop分配的内存。

g_main_run()

#define             g_main_run(loop)

Runs a main loop until it stops running.
运行主循环直到停止运行。

g_main_quit()

#define             g_main_quit(loop)

Stops the GMainLoop. If g_main_run() was called to run the GMainLoop, it will now return.
停止GMainLoop 。如果调用g_main_run()来运行GMainLoop ，它现在将返回。

g_main_is_running()

#define             g_main_is_running(loop)

Checks if the main loop is running.
检查主循环是否正在运行。

g_main_context_new () g_main_context_new()

GMainContext *
g_main_context_new (void);

Creates a new GMainContext structure.
创建一个新的GMainContext结构。

g_main_context_new_with_flags ()

GMainContext *
g_main_context_new_with_flags (GMainContextFlags flags);

Creates a new GMainContext structure.
创建一个新的GMainContext结构。

Since: 2.72 自： 2.72

g_main_context_ref ()

GMainContext *
g_main_context_ref (GMainContext *context);

Increases the reference count on a GMainContext object by one.
将GMainContext对象的引用计数增加一。

g_main_context_unref ()

void
g_main_context_unref (GMainContext *context);

Decreases the reference count on a GMainContext object by one. If the result is zero, free the context and free all associated memory.
将GMainContext对象的引用计数减一。如果结果为零，则释放上下文并释放所有关联的内存。

g_main_context_default ()
g_main_context_default()

GMainContext *
g_main_context_default (void);

Returns the global default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the "main" main loop. See also g_main_context_get_thread_default().
返回全局默认主上下文。这是当未显式指定主循环时用于主循环函数的主要上下文，并且对应于“main”主循环。参见 g_main_context_get_thread_default() 。

g_main_context_iteration ()
g_main_context_iteration()

gboolean
g_main_context_iteration (GMainContext *context,
                          gboolean may_block);

Runs a single iteration for the given main loop. This involves checking to see if any event sources are ready to be processed, then if no events sources are ready and may_block is TRUE, waiting for a source to become ready, then dispatching the highest priority events sources that are ready. Otherwise, if may_block is FALSE sources are not waited to become ready, only those highest priority events sources will be dispatched (if any), that are ready at this given moment without further waiting.
为给定的主循环运行一次迭代。这涉及检查是否有任何事件源准备好处理，如果没有事件源准备好并且may_block为TRUE ，则​​等待源准备好，然后分派准备就绪的最高优先级事件源。否则，如果may_block为FALSE则不会等待源准备就绪，只有那些最高优先级的事件源将被调度（如果有），这些事件源在给定时刻已准备好，无需进一步等待。

Note that even when may_block is TRUE, it is still possible for g_main_context_iteration() to return FALSE, since the wait may be interrupted for other reasons than an event source becoming ready.
请注意，即使may_block为TRUE ， g_main_context_iteration()仍然有可能返回FALSE ，因为等待可能会因事件源准备就绪以外的其他原因而中断。

g_main_iteration()

#define             g_main_iteration(may_block)

Runs a single iteration for the default GMainContext.
为默认的GMainContext运行一次迭代。

g_main_context_pending ()
g_main_context_pending()

gboolean
g_main_context_pending (GMainContext *context);

Checks if any sources have pending events for the given context.
检查是否有任何源有给定上下文的待处理事件。

g_main_pending

#define             g_main_pending()

Checks if any events are pending for the default GMainContext (i.e. ready to be processed).
检查默认GMainContext是否有任何待处理事件（即准备好处理）。

g_main_context_find_source_by_id ()

GSource *
g_main_context_find_source_by_id (GMainContext *context,
                                  guint source_id);

Finds a GSource given a pair of context and ID.
在给定一对上下文和 ID 的情况下查找GSource 。

It is a programmer error to attempt to look up a non-existent source.
尝试查找不存在的源是程序员的错误。

More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when scheduling an idle to run in another thread with g_idle_add(): the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the wrong source.
更具体地说：源 ID 可以在源被销毁后重新发布，因此使用此函数与可能已被删除的源 ID 永远是无效的。一个示例是，当使用g_idle_add()调度空闲在另一个线程中运行时：在其（现在无效）源 ID 上调用此函数时，空闲可能已经运行并被删除。该源 ID 可能已重新发布，从而导致针对错误的源执行操作。

g_main_context_find_source_by_user_data ()

GSource *
g_main_context_find_source_by_user_data
                               (GMainContext *context,
                                gpointer user_data);

Finds a source with the given user data for the callback. If multiple sources exist with the same user data, the first one found will be returned.
查找具有给定用户数据的回调源。如果存在具有相同用户数据的多个源，则将返回找到的第一个源。

g_main_context_find_source_by_funcs_user_data ()

GSource *
g_main_context_find_source_by_funcs_user_data
                               (GMainContext *context,
                                GSourceFuncs *funcs,
                                gpointer user_data);

Finds a source with the given source functions and user data. If multiple sources exist with the same source function and user data, the first one found will be returned.
查找具有给定源函数和用户数据的源。如果存在具有相同源函数和用户数据的多个源，则将返回找到的第一个源。

g_main_context_wakeup () g_main_context_wakeup()

void
g_main_context_wakeup (GMainContext *context);

If context is currently blocking in g_main_context_iteration() waiting for a source to become ready, cause it to stop blocking and return. Otherwise, cause the next invocation of g_main_context_iteration() to return without blocking.
如果context当前在g_main_context_iteration()中阻塞等待源准备就绪，则使其停止阻塞并返回。否则，导致g_main_context_iteration()的下一次调用返回而不阻塞。

This API is useful for low-level control over GMainContext; for example, integrating it with main loop implementations such as GMainLoop.
此 API 对于GMainContext的低级控制很有用；例如，将其与GMainLoop等主循环实现集成。

Another related use for this function is when implementing a main loop with a termination condition, computed from multiple threads:
此函数的另一个相关用途是实现具有终止条件的主循环（从多个线程计算）：

1
2
3
4
5
6

#define NUM_TASKS 10
static gint tasks_remaining = NUM_TASKS;  // (atomic)
...
 
while (g_atomic_int_get (&tasks_remaining) != 0)
  g_main_context_iteration (NULL, TRUE);

Then in a thread: 然后在一个线程中：

1
2
3
4

perform_work();

if (g_atomic_int_dec_and_test (&tasks_remaining))
  g_main_context_wakeup (NULL);

g_main_context_acquire ()
g_main_context_acquire()

gboolean
g_main_context_acquire (GMainContext *context);

Tries to become the owner of the specified context. If some other thread is the owner of the context, returns FALSE immediately. Ownership is properly recursive: the owner can require ownership again and will release ownership when g_main_context_release() is called as many times as g_main_context_acquire().
尝试成为指定上下文的所有者。如果某个其他线程是上下文的所有者，则立即返回FALSE 。所有权是正确递归的：所有者可以再次请求所有权，并在调用g_main_context_release()与g_main_context_acquire()次数相同时释放所有权。

You must be the owner of a context before you can call g_main_context_prepare(), g_main_context_query(), g_main_context_check(), g_main_context_dispatch().
您必须是上下文的所有者，然后才能调用g_main_context_prepare() 、 g_main_context_query() 、 g_main_context_check() 、 g_main_context_dispatch() 。

g_main_context_release ()
g_main_context_release()

void
g_main_context_release (GMainContext *context);

Releases ownership of a context previously acquired by this thread with g_main_context_acquire(). If the context was acquired multiple times, the ownership will be released only when g_main_context_release() is called as many times as it was acquired.
释放该线程之前使用g_main_context_acquire()获取的上下文的所有权。如果上下文被多次获取，则只有当g_main_context_release()被调用的次数与获取的次数相同时，所有权才会被释放。

g_main_context_is_owner ()

gboolean
g_main_context_is_owner (GMainContext *context);

Determines whether this thread holds the (recursive) ownership of this GMainContext. This is useful to know before waiting on another thread that may be blocking to get ownership of context .
确定此线程是否拥有此GMainContext的（递归）所有权。在等待可能阻塞的另一个线程获取context所有权之前了解这一点很有用。

Since: 2.10 自： 2.10

g_main_context_wait () g_main_context_wait()

gboolean
g_main_context_wait (GMainContext *context,
                     GCond *cond,
                     GMutex *mutex);

Tries to become the owner of the specified context, as with g_main_context_acquire(). But if another thread is the owner, atomically drop mutex and wait on cond until that owner releases ownership or until cond is signaled, then try again (once) to become the owner.
尝试成为指定上下文的所有者，如g_main_context_acquire() 。但是，如果另一个线程是所有者，则自动删除mutex并等待cond直到该所有者释放所有权或直到cond发出信号，然后再次尝试（一次）成为所有者。

g_main_context_prepare ()
g_main_context_prepare（）

gboolean
g_main_context_prepare (GMainContext *context,
                        gint *priority);

Prepares to poll sources within a main loop. The resulting information for polling is determined by calling g_main_context_query().
准备在主循环内轮询源。轮询的结果信息是通过调用g_main_context_query()确定的。

You must have successfully acquired the context with g_main_context_acquire() before you may call this function.
您必须先使用g_main_context_acquire()成功获取上下文，然后才能调用此函数。

g_main_context_query () g_main_context_query()

gint
g_main_context_query (GMainContext *context,
                      gint max_priority,
                      gint *timeout_,
                      GPollFD *fds,
                      gint n_fds);

Determines information necessary to poll this main loop. You should be careful to pass the resulting fds array and its length n_fds as is when calling g_main_context_check(), as this function relies on assumptions made when the array is filled.
确定轮询该主循环所需的信息。在调用g_main_context_check()时，您应该小心地传递生成的fds数组及其长度n_fds ，因为此函数依赖于数组填充时所做的假设。

You must have successfully acquired the context with g_main_context_acquire() before you may call this function.
您必须先使用g_main_context_acquire()成功获取上下文，然后才能调用此函数。

g_main_context_check () g_main_context_check()

gboolean
g_main_context_check (GMainContext *context,
                      gint max_priority,
                      GPollFD *fds,
                      gint n_fds);

Passes the results of polling back to the main loop. You should be careful to pass fds and its length n_fds as received from g_main_context_query(), as this functions relies on assumptions on how fds is filled.
将轮询结果传递回主循环。您应该小心传递从g_main_context_query()接收到的fds及其长度n_fds ，因为此函数依赖于对fds填充方式的假设。

You must have successfully acquired the context with g_main_context_acquire() before you may call this function.
您必须先使用g_main_context_acquire()成功获取上下文，然后才能调用此函数。

g_main_context_dispatch ()
g_main_context_dispatch()

void
g_main_context_dispatch (GMainContext *context);

Dispatches all pending sources.
调度所有待处理的源。

You must have successfully acquired the context with g_main_context_acquire() before you may call this function.
您必须先使用g_main_context_acquire()成功获取上下文，然后才能调用此函数。

g_main_context_set_poll_func ()

void
g_main_context_set_poll_func (GMainContext *context,
                              GPollFunc func);

Sets the function to use to handle polling of file descriptors. It will be used instead of the poll() system call (or GLib's replacement function, which is used where poll() isn't available).
设置用于处理文件描述符轮询的函数。将使用它将代替poll()系统调用（或 GLib 的替换函数，该函数在poll()不可用的情况下使用）。

This function could possibly be used to integrate the GLib event loop with an external event loop.
该函数可用于将 GLib 事件循环与外部事件循环集成。

g_main_context_get_poll_func ()

GPollFunc
g_main_context_get_poll_func (GMainContext *context);

Gets the poll function set by g_main_context_set_poll_func().
获取由以下设置的 poll 函数 g_main_context_set_poll_func() 。

GPollFunc () GPollFunc()

gint
(*GPollFunc) (GPollFD *ufds,
              guint nfsd,
              gint timeout_);

Specifies the type of function passed to g_main_context_set_poll_func(). The semantics of the function should match those of the poll() system call.
指定传递给的函数类型 g_main_context_set_poll_func() 。该函数的语义应与poll()系统调用的语义相匹配。

g_main_context_add_poll ()
g_main_context_add_poll()

void
g_main_context_add_poll (GMainContext *context,
                         GPollFD *fd,
                         gint priority);

Adds a file descriptor to the set of file descriptors polled for this context. This will very seldom be used directly. Instead a typical event source will use g_source_add_unix_fd() instead.
将文件描述符添加到为此上下文轮询的文件描述符集中。这很少会被直接使用。相反，典型的事件源将使用g_source_add_unix_fd()代替。

g_main_context_remove_poll ()

void
g_main_context_remove_poll (GMainContext *context,
                            GPollFD *fd);

Removes file descriptor from the set of file descriptors to be polled for a particular context.
从要轮询特定上下文的文件描述符集中删除文件描述符。

g_main_depth () g_main_深度（）

gint
g_main_depth (void);

Returns the depth of the stack of calls to g_main_context_dispatch() on any GMainContext in the current thread. That is, when called from the toplevel, it gives 0. When called from within a callback from g_main_context_iteration() (or g_main_loop_run(), etc.) it returns 1. When called from within a callback to a recursive call to g_main_context_iteration(), it returns 2. And so forth.
返回当前线程中任何GMainContext上对g_main_context_dispatch()的调用堆栈的深度。也就是说，当从顶层调用时，它给出 0。当从g_main_context_iteration() （或g_main_loop_run()等）的回调中调用时，它返回 1。当从g_main_context_iteration()递归调用的回调中调用时，它返回 1。 ，它返回 2。依此类推。

This function is useful in a situation like the following: Imagine an extremely simple "garbage collected" system.
该函数在如下情况下非常有用：想象一个极其简单的“垃圾收集”系统。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

static GList *free_list;

gpointer
allocate_memory (gsize size)
{ 
  gpointer result = g_malloc (size);
  free_list = g_list_prepend (free_list, result);
  return result;
}

void
free_allocated_memory (void)
{
  GList *l;
  for (l = free_list; l; l = l->next);
    g_free (l->data);
  g_list_free (free_list);
  free_list = NULL;
 }

[...]

while (TRUE); 
 {
   g_main_context_iteration (NULL, TRUE);
   free_allocated_memory();
  }

This works from an application, however, if you want to do the same thing from a library, it gets more difficult, since you no longer control the main loop. You might think you can simply use an idle function to make the call to free_allocated_memory(), but that doesn't work, since the idle function could be called from a recursive callback. This can be fixed by using g_main_depth()
这可以在应用程序中工作，但是，如果您想从库中执行相同的操作，则会变得更加困难，因为您不再控制主循环。您可能认为可以简单地使用空闲函数来调用free_allocated_memory() ，但这不起作用，因为可以从递归回调中调用空闲函数。这可以通过使用g_main_depth()来修复

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

gpointer
allocate_memory (gsize size)
{ 
  FreeListBlock *block = g_new (FreeListBlock, 1);
  block->mem = g_malloc (size);
  block->depth = g_main_depth ();   
  free_list = g_list_prepend (free_list, block);
  return block->mem;
}

void
free_allocated_memory (void)
{
  GList *l;
  
  int depth = g_main_depth ();
  for (l = free_list; l; );
    {
      GList *next = l->next;
      FreeListBlock *block = l->data;
      if (block->depth > depth)
        {
          g_free (block->mem);
          g_free (block);
          free_list = g_list_delete_link (free_list, l);
        }
              
      l = next;
    }
  }

There is a temptation to use g_main_depth() to solve problems with reentrancy. For instance, while waiting for data to be received from the network in response to a menu item, the menu item might be selected again. It might seem that one could make the menu item's callback return immediately and do nothing if g_main_depth() returns a value greater than 1. However, this should be avoided since the user then sees selecting the menu item do nothing. Furthermore, you'll find yourself adding these checks all over your code, since there are doubtless many, many things that the user could do. Instead, you can use the following techniques:
人们倾向于使用g_main_depth()来解决可重入问题。例如，当等待从网络接收响应于菜单项的数据时，可以再次选择该菜单项。如果g_main_depth()返回大于 1 的值，似乎可以使菜单项的回调立即返回并且不执行任何操作。但是，应该避免这种情况，因为用户会看到选择菜单项不执行任何操作。此外，您会发现自己在代码中添加了这些检查，因为用户无疑可以做很多很多事情。相反，您可以使用以下技术：

g_main_current_source () g_main_current_source()

GSource *
g_main_current_source (void);

Returns the currently firing source for this thread.
返回该线程当前的触发源。

Since: 2.12 自： 2.12

g_main_set_poll_func()

#define             g_main_set_poll_func(func)

Sets the function to use for the handle polling of file descriptors for the default main context.
设置用于默认主上下文的文件描述符句柄轮询的函数。

g_main_context_invoke () g_main_context_invoke()

void
g_main_context_invoke (GMainContext *context,
                       GSourceFunc function,
                       gpointer data);

Invokes a function in such a way that context is owned during the invocation of function .
以在调用function期间拥有context的方式调用函数。

If context is NULL then the global default main context — as returned by g_main_context_default() — is used.
如果context为NULL ，则使用g_main_context_default()返回的全局默认主上下文。

If context is owned by the current thread, function is called directly. Otherwise, if context is the thread-default main context of the current thread and g_main_context_acquire() succeeds, then function is called and g_main_context_release() is called afterwards.
如果context由当前线程拥有，则直接调用function 。否则，如果context是当前线程的线程默认主上下文，并且g_main_context_acquire()成功，则调用function ，然后调用g_main_context_release() 。

In any other case, an idle source is created to call function and that source is attached to context (presumably to be run in another thread). The idle source is attached with G_PRIORITY_DEFAULT priority. If you want a different priority, use g_main_context_invoke_full().
在任何其他情况下，都会创建一个空闲源来调用function ，并将该源附加到context （可能在另一个线程中运行）。空闲源附加G_PRIORITY_DEFAULT优先级。如果您想要不同的优先级，请使用g_main_context_invoke_full() 。

Note that, as with normal idle functions, function should probably return FALSE. If it returns TRUE, it will be continuously run in a loop (and may prevent this call from returning).
请注意，与正常的空闲函数一样， function可能应该返回FALSE 。如果它返回TRUE ，它将在循环中连续运行（并且可能会阻止此调用返回）。

Since: 2.28 自： 2.28

g_main_context_invoke_full ()

void
g_main_context_invoke_full (GMainContext *context,
                            gint priority,
                            GSourceFunc function,
                            gpointer data,
                            GDestroyNotify notify);

Invokes a function in such a way that context is owned during the invocation of function .
以在调用function期间拥有context的方式调用函数。

This function is the same as g_main_context_invoke() except that it lets you specify the priority in case function ends up being scheduled as an idle and also lets you give a GDestroyNotify for data .
此函数与g_main_context_invoke()相同，只是它允许您指定优先级，以防function最终被安排为空闲，并且还允许您为data提供GDestroyNotify 。

notify should not assume that it is called from any particular thread or with any particular context acquired.
notify不应假设它是从任何特定线程调用的，或者是在获取任何特定上下文的情况下调用的。

Since: 2.28 自： 2.28

g_main_context_pusher_new ()

GMainContextPusher *
g_main_context_pusher_new (GMainContext *main_context);

Push main_context as the new thread-default main context for the current thread, using g_main_context_push_thread_default(), and return a new GMainContextPusher. Pop with g_main_context_pusher_free(). Using g_main_context_pop_thread_default() on main_context while a GMainContextPusher exists for it can lead to undefined behaviour.
将main_context推入当前线程的新线程默认主上下文，使用 g_main_context_push_thread_default() ，并返回一个新的GMainContextPusher 。使用g_main_context_pusher_free()弹出。使用 g_main_context_pop_thread_default() 当GMainContextPusher存在时，在main_context上可能会导致未定义的行为。

Using two GMainContextPushers in the same scope is not allowed, as it leads to an undefined pop order.
不允许在同一范围内使用两个GMainContextPushers ，因为这会导致未定义的弹出顺序。

This is intended to be used with g_autoptr(). Note that g_autoptr() is only available when using GCC or clang, so the following example will only work with those compilers:
这旨在与g_autoptr()一起使用。请注意， g_autoptr()仅在使用 GCC 或 clang 时可用，因此以下示例仅适用于这些编译器：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

typedef struct
{
  ...
  GMainContext *context;
  ...
} MyObject;

static void
my_object_do_stuff (MyObject *self)
{
  g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context);

  // Code with main context as the thread default here

  if (cond)
    // No need to pop
    return;

  // Optionally early pop
  g_clear_pointer (&pusher, g_main_context_pusher_free);

  // Code with main context no longer the thread default here
}

Since: 2.64 自： 2.64

g_main_context_pusher_free ()

void
g_main_context_pusher_free (GMainContextPusher *pusher);

Pop pusher ’s main context as the thread default main context. See g_main_context_pusher_new() for details.
Pop pusher的主上下文作为线程默认主上下文。有关详细信息，请参阅g_main_context_pusher_new() 。

This will pop the GMainContext as the current thread-default main context, but will not call g_main_context_unref() on it.
这会将GMainContext弹出为当前线程默认主上下文，但不会对其调用g_main_context_unref() 。

Since: 2.64 自： 2.64

g_main_context_get_thread_default ()
g_main_context_get_thread_default()

GMainContext *
g_main_context_get_thread_default (void);

Gets the thread-default GMainContext for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or g_main_context_ref_thread_default() to get a GMainContext to add their GSources to. (Note that even in single-threaded programs applications may sometimes want to temporarily push a non-default context, so it is not safe to assume that this will always return NULL if you are running in the default thread.)
获取此线程的线程默认GMainContext 。希望能够在默认上下文以外的上下文中运行的异步操作应调用此方法或 g_main_context_ref_thread_default() 获取GMainContext以将其GSource添加到其中。 （请注意，即使在单线程程序中，应用程序有时也可能想要临时推送非默认上下文，因此如果您在默认线程中运行，则假设这将始终返回NULL是不安全的。）

If you need to hold a reference on the context, use g_main_context_ref_thread_default() instead.
如果您需要保留上下文的引用，请使用 g_main_context_ref_thread_default() 反而。

Since: 2.22 自： 2.22

g_main_context_ref_thread_default ()

GMainContext *
g_main_context_ref_thread_default (void);

Gets the thread-default GMainContext for this thread, as with g_main_context_get_thread_default(), but also adds a reference to it with g_main_context_ref(). In addition, unlike g_main_context_get_thread_default(), if the thread-default context is the global default context, this will return that GMainContext (with a ref added to it) rather than returning NULL.
获取该线程的线程默认GMainContext ，如下所示 g_main_context_get_thread_default() ，而且还使用g_main_context_ref()添加对它的引用。另外，与 g_main_context_get_thread_default() ，如果线程默认上下文是全局默认上下文，这将返回GMainContext （添加了引用）而不是返回NULL 。

Since: 2.32 自： 2.32

g_main_context_push_thread_default ()
g_main_context_push_thread_default()

void
g_main_context_push_thread_default (GMainContext *context);

Acquires context and sets it as the thread-default context for the current thread. This will cause certain asynchronous operations (such as most gio-based I/O) which are started in this thread to run under context and deliver their results to its main loop, rather than running under the global default context in the main thread. Note that calling this function 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 the context used by functions like g_idle_add().
获取context并将其设置为当前线程的线程默认上下文。这将导致在此线程中启动的某些异步操作（例如大多数基于 gio 的 I/O）在context下运行并将其结果传递到其主循环，而不是在主线程中的全局默认上下文下运行。请注意，调用此函数会更改返回的上下文 g_main_context_get_thread_default() ，而不是g_main_context_default()返回的值，因此它不会影响g_idle_add()等函数使用的上下文。

Normally you would call this function shortly after creating a new thread, passing it a GMainContext which will be run by a GMainLoop in that thread, to set a new default context for all async operations in that thread. In this case you may not need to ever call g_main_context_pop_thread_default(), assuming you want the new GMainContext to be the default for the whole lifecycle of the thread.
通常，您会在创建新线程后不久调用此函数，并向其传递将由该线程中的GMainLoop运行的GMainContext ，以便为该线程中的所有异步操作设置新的默认上下文。在这种情况下，您可能不需要致电 g_main_context_pop_thread_default() ，假设您希望新的GMainContext成为线程整个生命周期的默认值。

If you don't have control over how the new thread was created (e.g. in the new thread isn't newly created, or if the thread life cycle is managed by a GThreadPool), it is always suggested to wrap the logic that needs to use the new GMainContext inside a g_main_context_push_thread_default() / g_main_context_pop_thread_default() pair, otherwise threads that are re-used will end up never explicitly releasing the GMainContext reference they hold.
如果您无法控制新线程的创建方式（例如，新线程不是新创建的，或者线程生命周期由GThreadPool管理），则始终建议包装需要的逻辑在 a 中使用新的GMainContext g_main_context_push_thread_default() / g_main_context_pop_thread_default() 配对，否则重用的线程最终将永远不会显式释放它们持有的GMainContext引用。

In some cases you may want to schedule a single operation in a non-default context, or temporarily use a non-default context in the main thread. In that case, you can wrap the call to the asynchronous operation inside a g_main_context_push_thread_default() / g_main_context_pop_thread_default() pair, but it is up to you to ensure that no other asynchronous operations accidentally get started while the non-default context is active.
在某些情况下，您可能希望在非默认上下文中安排单个操作，或者在主线程中临时使用非默认上下文。在这种情况下，您可以将对异步操作的调用包装在 g_main_context_push_thread_default() / g_main_context_pop_thread_default() 配对，但您需要确保在非默认上下文处于活动状态时不会意外启动其他异步操作。

Beware that libraries that predate this function may not correctly handle being used from a thread with a thread-default context. Eg, see g_file_supports_thread_contexts().
请注意，早于该函数的库可能无法正确处理具有线程默认上下文的线程的使用。例如，参见 g_file_supports_thread_contexts() 。

Since: 2.22 自： 2.22

g_main_context_pop_thread_default ()
g_main_context_pop_thread_default()

void
g_main_context_pop_thread_default (GMainContext *context);

Pops context off the thread-default context stack (verifying that it was on the top of the stack).
将context从线程默认上下文堆栈中弹出（验证它位于堆栈顶部）。

Since: 2.22 自： 2.22

g_timeout_source_new () g_timeout_source_new()

GSource *
g_timeout_source_new (guint interval);

Creates a new timeout source.
创建新的超时源。

The source will not initially be associated with any GMainContext and must be added to one with g_source_attach() before it will be executed.
该源最初不会与任何GMainContext关联，并且必须在执行之前使用g_source_attach()添加到 GMainContext 中。

The interval given is in terms of monotonic time, not wall clock time. See g_get_monotonic_time().
给出的间隔是单调时间，而不是挂钟时间。请参阅g_get_monotonic_time() 。

g_timeout_source_new_seconds ()

GSource *
g_timeout_source_new_seconds (guint interval);

Creates a new timeout source.
创建新的超时源。

The source will not initially be associated with any GMainContext and must be added to one with g_source_attach() before it will be executed.
该源最初不会与任何GMainContext关联，并且必须在执行之前使用g_source_attach()添加到 GMainContext 中。

The scheduling granularity/accuracy of this timeout source will be in seconds.
该超时源的调度粒度/精度将以秒为单位。

The interval given is in terms of monotonic time, not wall clock time. See g_get_monotonic_time().
给出的间隔是单调时间，而不是挂钟时间。请参阅g_get_monotonic_time() 。

Since: 2.14 自： 2.14

g_timeout_add () g_timeout_add()

guint
g_timeout_add (guint interval,
               GSourceFunc function,
               gpointer data);

Sets a function to be called at regular intervals, with the default priority, G_PRIORITY_DEFAULT.
设置定期调用的函数，使用默认优先级G_PRIORITY_DEFAULT 。

The given function is called repeatedly until it returns G_SOURCE_REMOVE or FALSE, at which point the timeout is automatically destroyed and the function will not be called again. The first call to the function will be at the end of the first interval .
给定的function会被重复调用，直到返回G_SOURCE_REMOVE或FALSE ，此时超时会自动销毁，并且该函数不会再次被调用。第一次调用该函数将在第一个interval结束时进行。

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays).
请注意，由于其他事件源的处理，超时函数可能会延迟。因此，不应依赖它们来进行精确计时。每次调用超时函数后，都会根据当前时间和给定的时间间隔重新计算下一次超时的时间（它不会尝试“弥补”延迟中损失的时间）。

See memory management of sources for details on how to handle the return value and memory management of data .
有关如何处理返回值和data内存管理的详细信息，请参阅源的内存管理。

If you want to have a timer in the "seconds" range and do not care about the exact time of the first call of the timer, use the g_timeout_add_seconds() function; this function allows for more optimizations and more efficient system power usage.
如果你想有一个“秒”范围内的计时器，并且不关心第一次调用计时器的确切时间，请使用g_timeout_add_seconds()函数；此功能可以实现更多优化和更有效的系统电源使用。

This internally creates a main loop source using g_timeout_source_new() and attaches it to the global GMainContext using g_source_attach(), so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context.
这在内部使用g_timeout_source_new()创建一个主循环源，并使用g_source_attach()将其附加到全局GMainContext ，因此回调将在运行该主上下文的任何线程中调用。如果您需要更好的控制或使用自定义主上下文，您可以手动执行这些步骤。

It is safe to call this function from any thread.
从任何线程调用此函数都是安全的。

The interval given is in terms of monotonic time, not wall clock time. See g_get_monotonic_time().
给出的间隔是单调时间，而不是挂钟时间。请参阅g_get_monotonic_time() 。

g_timeout_add_full () g_timeout_add_full()

guint
g_timeout_add_full (gint priority,
                    guint interval,
                    GSourceFunc function,
                    gpointer data,
                    GDestroyNotify notify);

Sets a function to be called at regular intervals, with the given priority. The function is called repeatedly until it returns FALSE, at which point the timeout is automatically destroyed and the function will not be called again. The notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first interval .
设置一个以给定优先级定期调用的函数。该函数会被重复调用，直到返回FALSE ，此时超时自动销毁，并且该函数不会再次被调用。当超时被销毁时，会调用notify函数。第一次调用该函数将在第一个interval结束时进行。

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays).
请注意，由于其他事件源的处理，超时函数可能会延迟。因此，不应依赖它们来进行精确计时。每次调用超时函数后，都会根据当前时间和给定的时间间隔重新计算下一次超时的时间（它不会尝试“弥补”延迟中损失的时间）。

See memory management of sources for details on how to handle the return value and memory management of data .
有关如何处理返回值和data内存管理的详细信息，请参阅源的内存管理。

This internally creates a main loop source using g_timeout_source_new() and attaches it to the global GMainContext using g_source_attach(), so the callback will be invoked in whichever thread is running that main context. You can do these steps manually if you need greater control or to use a custom main context.
这在内部使用g_timeout_source_new()创建一个主循环源，并使用g_source_attach()将其附加到全局GMainContext ，因此回调将在运行该主上下文的任何线程中调用。如果您需要更好的控制或使用自定义主上下文，您可以手动执行这些步骤。

The interval given is in terms of monotonic time, not wall clock time. See g_get_monotonic_time().
给出的间隔是单调时间，而不是挂钟时间。请参阅g_get_monotonic_time() 。

[rename-to g_timeout_add]
[重命名为g_timeout_add]

g_timeout_add_seconds () g_timeout_add_seconds()

guint
g_timeout_add_seconds (guint interval,
                       GSourceFunc function,
                       gpointer data);

Sets a function to be called at regular intervals with the default priority, G_PRIORITY_DEFAULT.
设置一个以默认优先级G_PRIORITY_DEFAULT定期调用的函数。

The function is called repeatedly until it returns G_SOURCE_REMOVE or FALSE, at which point the timeout is automatically destroyed and the function will not be called again.
该函数会被重复调用，直到返回G_SOURCE_REMOVE或FALSE ，此时超时自动销毁，该函数不会再次被调用。

This internally creates a main loop source using g_timeout_source_new_seconds() and attaches it to the main loop context using g_source_attach(). You can do these steps manually if you need greater control. Also see g_timeout_add_seconds_full().
这在内部创建了一个主循环源，使用 g_timeout_source_new_seconds() 并使用g_source_attach()将其附加到主循环上下文。如果您需要更好的控制，您可以手动执行这些步骤。另请参阅g_timeout_add_seconds_full() 。

It is safe to call this function from any thread.
从任何线程调用此函数都是安全的。

Note that the first call of the timer may not be precise for timeouts of one second. If you need finer precision and have such a timeout, you may want to use g_timeout_add() instead.
请注意，计时器的第一次调用对于一秒的超时可能不精确。如果您需要更精细的精度并有这样的超时，您可能需要使用g_timeout_add()代替。

See memory management of sources for details on how to handle the return value and memory management of data .
有关如何处理返回值和data内存管理的详细信息，请参阅源的内存管理。

The interval given is in terms of monotonic time, not wall clock time. See g_get_monotonic_time().
给出的间隔是单调时间，而不是挂钟时间。请参阅g_get_monotonic_time() 。

Since: 2.14 自： 2.14

g_timeout_add_seconds_full ()

guint
g_timeout_add_seconds_full (gint priority,
                            guint interval,
                            GSourceFunc function,
                            gpointer data,
                            GDestroyNotify notify);

Sets a function to be called at regular intervals, with priority .
设置一个定期调用的函数， priority为 。

The function is called repeatedly until it returns G_SOURCE_REMOVE or FALSE, at which point the timeout is automatically destroyed and the function will not be called again.
该函数会被重复调用，直到返回G_SOURCE_REMOVE或FALSE ，此时超时自动销毁，该函数不会再次被调用。

Unlike g_timeout_add(), this function operates at whole second granularity. The initial starting point of the timer is determined by the implementation and the implementation is expected to group multiple timers together so that they fire all at the same time. To allow this grouping, the interval to the first timer is rounded and can deviate up to one second from the specified interval. Subsequent timer iterations will generally run at the specified interval.
与g_timeout_add()不同，该函数以整个秒粒度运行。计时器的初始起点由实现确定，并且预期实现将多个计时器分组在一起，以便它们同时触发。为了允许这种分组，第一个计时器的interval被舍入，并且可以与指定的时间间隔最多偏差一秒。后续的计时器迭代通常会按照指定的时间间隔运行。

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval
请注意，由于其他事件源的处理，超时函数可能会延迟。因此，不应依赖它们来进行精确计时。每次调用超时函数后，都会根据当前时间和给定的interval重新计算下一次超时的时间

See memory management of sources for details on how to handle the return value and memory management of data .
有关如何处理返回值和data内存管理的详细信息，请参阅源的内存管理。

If you want timing more precise than whole seconds, use g_timeout_add() instead.
如果您希望计时比整秒更精确，请改用g_timeout_add() 。

The grouping of timers to fire at the same time results in a more power and CPU efficient behavior so if your timer is in multiples of seconds and you don't require the first timer exactly one second from now, the use of g_timeout_add_seconds() is preferred over g_timeout_add().
同时触发的计时器分组会导致更省电和更高效的 CPU 行为，因此，如果您的计时器以秒为单位，并且您不需要从现在起正好一秒后使用第一个计时器，则使用g_timeout_add_seconds()是优于g_timeout_add() 。

This internally creates a main loop source using g_timeout_source_new_seconds() and attaches it to the main loop context using g_source_attach(). You can do these steps manually if you need greater control.
这在内部创建了一个主循环源，使用 g_timeout_source_new_seconds() 并使用g_source_attach()将其附加到主循环上下文。如果您需要更好的控制，您可以手动执行这些步骤。

It is safe to call this function from any thread.
从任何线程调用此函数都是安全的。

The interval given is in terms of monotonic time, not wall clock time. See g_get_monotonic_time().
给出的间隔是单调时间，而不是挂钟时间。请参阅g_get_monotonic_time() 。

[rename-to g_timeout_add_seconds]
[重命名为g_timeout_add_seconds]

Since: 2.14 自： 2.14

g_idle_source_new () g_idle_source_new()

GSource *
g_idle_source_new (void);

Creates a new idle source.
创建一个新的空闲源。

The source will not initially be associated with any GMainContext and must be added to one with g_source_attach() before it will be executed. Note that the default priority for idle sources is G_PRIORITY_DEFAULT_IDLE, as compared to other sources which have a default priority of G_PRIORITY_DEFAULT.
该源最初不会与任何GMainContext关联，并且必须在执行之前使用g_source_attach()添加到 GMainContext 中。请注意，与默认优先级为G_PRIORITY_DEFAULT的其他源相比，空闲源的默认优先级为G_PRIORITY_DEFAULT_IDLE 。

g_idle_add () g_idle_add()

guint
g_idle_add (GSourceFunc function,
            gpointer data);

Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the default idle priority, G_PRIORITY_DEFAULT_IDLE. If the function returns FALSE it is automatically removed from the list of event sources and will not be called again.
添加一个函数，只要默认主循环中没有待处理的更高优先级事件，就会调用该函数。该函数被赋予默认的空闲优先级G_PRIORITY_DEFAULT_IDLE 。如果函数返回FALSE它将自动从事件源列表中删除，并且不会再次调用。