@c -*-texinfo-*-
@c This is part of the GNU G-Golf Reference Manual.
@c Copyright (C) 2016 - 2020 Free Software Foundation, Inc.
@c See the file g-golf.texi for copying conditions.


@c @defindex tl


@node The Main Event Loop
@subsection The Main Event Loop

G-Golf Glib Main Event Loop low level API.@*
The Main Event Loop — manages all available sources of events


@subheading Procedures

@indentedblock
@table @code
@item @ref{g-main-loop-new}
@item @ref{g-main-loop-run}
@item @ref{g-main-loop-ref}
@item @ref{g-main-loop-unref}
@item @ref{g-main-loop-quit}
@item @ref{g-main-context-new}
@item @ref{g-main-context-default}
@item @ref{g-timeout-source-new}
@item @ref{g-timeout-source-new-seconds}
@item @ref{g-idle-source-new}
@item @ref{g-source-ref-count}
@item @ref{g-source-ref}
@item @ref{g-source-unref}
@item @ref{g-source-free}
@item @ref{g-source-attach}
@item @ref{g-source-destroy}
@item @ref{g-source-is-destroyed?}
@item @ref{g-source-set-priority}
@item @ref{g-source-get-priority}
@item @ref{g-source-remove}
@end table
@end indentedblock


@c @subheading Types and Values

@c @indentedblock
@c @table @code
@c @item @ref{<gi-enum>}
@c @end table
@c @end indentedblock


@c @subheading Struct Hierarchy

@c @indentedblock
@c GIBaseInfo           	       		@*
@c @ @ +--- GIRegisteredTypeInfo  		@*
@c @ @ @ @ @ @ @ @ @ @ @  +--- GIEnumInfo
@c @end indentedblock


@subheading Description

The main event loop manages all the available sources of events for GLib
and GTK+ applications. These events can come from any number of
different types of sources such as file descriptors (plain files, pipes
or sockets) and timeouts. New types of event sources can also be added
using @code{g-source-attach}.

Please read @uref{@value{UGLIB-Main-Event-Loop}, The Main Event Loop}
section from the Glib reference manual for a complete description.


@subheading Procedures

Note: in this section, the @var{loop}, @var{context} and @var{source}
arguments are [must be] pointers to a @code{GMainLoop}, a
@code{GMainContext} and a @var{GSource} respectively.


@anchor{g-main-loop-new}
@deffn Procedure g-main-loop-new [context #f] [is-running? #f]

Returns a pointer to a new @code{GMainLoop}.

Creates a new @code{GMainLoop} structure.

The @var{context} must be a pointer to a @code{GMainContext} of
@code{#f}, in which case the default context is used.  When
@var{is-running?} is @code{#t}, it indicates that the loop is
running. This is not very important since calling @code{g-main-loop-run}
will set this to @code{#t} anyway.
@end deffn


@anchor{g-main-loop-ref}
@deffn Procedure g-main-loop-ref loop

Returns loop.

Increases the @var{loop} reference count by one.
@end deffn


@anchor{g-main-loop-unref}
@deffn Procedure g-main-loop-unref loop

Returns nothing.

Decreases the @var{loop} reference count by one. If the result is zero,
free the loop and free all associated memory.
@end deffn


@anchor{g-main-loop-run}
@deffn Procedure g-main-loop-run loop

Returns nothing.

Runs a main loop until @ref{g-main-loop-quit} is called on the
@var{loop}. If this is called for the thread of the loop's
@code{GMainContext}, it will process events from the @var{loop},
otherwise it will simply wait.
@end deffn


@anchor{g-main-loop-quit}
@deffn Procedure g-main-loop-quit loop

Returns nothing.

Stops a @code{GMainLoop} from running. Any calls to
@ref{g-main-loop-run} for the @var{loop} will return.

Note that sources that have already been dispatched when
@code{g-main-loop-quit} is called will still be executed.
@end deffn


@anchor{g-main-context-new}
@deffn Procedure g-main-context-new

Returns a pointer.

Creates and returns a (pointer to a) new @code{GMainContext} structure.
@end deffn


@anchor{g-main-context-default}
@deffn Procedure g-main-context-default

Returns a pointer.

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 @samp{main} main loop.

@c See also g_main_context_get_thread_default().
@end deffn


@anchor{g-timeout-source-new}
@deffn Procedure g-timeout-source-new interval

Returns a pointer.

Creates and returns (a pointer to) a new (timeout) @code{GSource}.

The source will not initially be associated with any @code{GMainContext}
and must be added to one with @ref{g-source-attach} before it will be
executed.

The timeout @var{interval} is in milliseconds.
@end deffn


@anchor{g-timeout-source-new-seconds}
@deffn Procedure g-timeout-source-new-seconds interval

Returns a pointer.

Creates and returns (a pointer to) a new (timeout) @code{GSource}.

The source will not initially be associated with any @code{GMainContext}
and must be added to one with @ref{g-source-attach} before it will be
executed.

The timeout @var{interval} is in seconds.
@end deffn


@anchor{g-idle-source-new}
@deffn Procedure g-idle-source-new

Returns a pointer.

Creates and returns (a pointer to) a new (idle) @code{GSource}.

The source will not initially be associated with any @code{GMainContext}
and must be added to one with @ref{g-source-attach} before it will be
executed. Note that the default priority for idle sources is @code{200},
as compared to other sources which have a default priority of
@code{300}.
@end deffn


@anchor{g-source-ref-count}
@deffn Procedure g-source-ref-count source

Returns an integer.

Obtains and returns the reference count of @var{source}.
@end deffn


@anchor{g-source-ref}
@deffn Procedure g-source-ref source

Returns @var{source}.

Increases the @var{source} reference count by one.
@end deffn


@anchor{g-source-unref}
@deffn Procedure g-source-unref source

Returns nothing.

Decreases the @var{source} reference count by one. If the resulting
reference count is zero the source and associated memory will be
destroyed.
@end deffn


@anchor{g-source-free}
@deffn Procedure g-source-free source

Returns nothing.

Calls @ref{g-source-destroy} and decrements the reference count of
@var{source} to 0 (so @var{source} will be destroyed and freed).
@end deffn


@anchor{g-source-attach}
@deffn Procedure g-source-attach source context

Returns an integer.

Adds @var{source} to @var{context} so that it will be executed within
that context.

Returns the ID (greater than 0) for the @var{source} within the
@var{context}.

Remove it by calling @ref{g-source-destroy}.
@end deffn


@anchor{g-source-destroy}
@deffn Procedure g-source-destroy source

Returns nothing.

Removes @var{source} from its @code{GMainContext}, if any, and mark it
as destroyed. The source cannot be subsequently added to another
context. It is safe to call this on sources which have already been
removed from their context.

This does not unref @var{source}: if you still hold a reference, use
g-source-unref to drop it.
@end deffn


@anchor{g-source-is-destroyed?}
@deffn Procedure g-source-is-destroyed? source

Returns #t if @var{source} has been destroyed. Otherwise, it returns #f.

Once a source is destroyed it cannot be un-destroyed.
@end deffn


@anchor{g-source-set-priority}
@deffn Procedure g-source-set-priority source priority

Returns nothing.

Sets the @var{source} priority. While the main loop is being run, a
source will be dispatched if it is ready to be dispatched and no sources
at a higher (numerically smaller) priority are ready to be dispatched.

A child source always has the same priority as its parent. It is not
permitted to change the priority of a source once it has been added as a
child of another source.
@end deffn


@anchor{g-source-get-priority}
@deffn Procedure g-source-get-priority source priority

Returns an integer.

Obtains and returns the @var{source} priority.
@end deffn


@anchor{g-source-remove}
@deffn Procedure g-source-remove id

Returns #t.

Removes the source with the given @var{id} from the default main
context. You must use @ref{g-source-destroy} for sources added to a
non-default main context.

It is an error to attempt to remove a non-existent source.

Source IDs can be reissued after a source has been destroyed. This could
lead to the removal operation being performed against the wrong source,
unless you are cautious.

For historical reasons, this procedure always returns #t.
@end deffn


@c @subheading Types and Values
