About all my projects
Gnome::Glib::Source

Gnome::Glib::Source

manages all available sources of events

Description

To get a bigger picture, you can read the description of class Gnome::Glib::MainContext.

Synopsis

Declaration

unit class Gnome::Glib::Source;
also is Gnome::N::TopLevelClassSupport;

Types

N-GSourceFuncs

The N-GSourceFuncs struct contains a table of functions used to handle event sources in a generic manner.

For idle sources, the prepare and check functions always return TRUE to indicate that the source is always ready to be processed. The prepare function also returns a timeout value of 0 to ensure that the poll() call doesn't block (since that would be time wasted which could have been spent running the idle function).

For timeout sources, the prepare and check functions both return TRUE if the timeout interval has expired. The prepare function also returns a timeout value to ensure that the poll() call doesn't block too long and miss the next timeout.

For file descriptor sources, the prepare function typically returns FALSE, since it must wait until poll() has been called before it knows whether any events need to be processed. It sets the returned timeout to -1 to indicate that it doesn't mind how long the poll() call blocks. In the check function, it tests the results of the poll() call to see if the required condition has been met, and returns TRUE if so.

The structure of N-GSourceFuncs is

class N-GSourceFuncs is repr('CStruct') {
  has Callable $.prepare ( N-GObject $source, gint $timeout --> gboolean ) is rw;
  has Callable $.check ( N-GObject $source --> gboolean ) is rw;
  has Callable $.dispatch (
  N-GObject source, GSourceFunc $callback, gpointer $user_data
  --> gboolean
) is rw;
  has Callable $.finalize ( N-GObject $source) is rw;
};

  • function prepare

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 >= 0. 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. If prepare returns a timeout and the source also has a ready time set, then the lower of the two will be used.

sub prepare ( N-GObject $source, gint $timeout --> gboolean )

  • function check

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.

  • function dispatch

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 g_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 G_SOURCE_REMOVE if the source should be removed or G_SOURCE_CONTINUE to keep it.

  • function finalize

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 GMainContext, but it will still have its final reference count, so methods can be called on it from within this function.

Methods

new

:idle

Create a new Source object to run processes in idle time. The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with 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.

multi method new ( :idle! )

:timout

Creates a new timeout source. The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with attach() before it will be executed.

The interval given is in terms of monotonic time, not wall clock time. See get-monotonic-time().

multi method new ( Int :$timeout!, Bool :$seconds = False )

  • UInt $interval; the timeout interval in milliseconds.

:native-object

Create a Source object using a native object from elsewhere. See also Gnome::N::TopLevelClassSupport.

multi method new ( N-GObject :$native-object! )

add-child-source

Adds child-source to source as a "polled" source; when source is added to a Gnome::Glib::MainContext, child-source will be automatically added with the same priority, when child-source is triggered, it will cause source to dispatch (in addition to calling its own callback), and when source is destroyed, it will destroy child-source as well. (source will also still be dispatched if its own prepare/check functions indicate that it is ready.)

If you don't need child-source to do anything on its own when it triggers, you can call set-dummy-callback() on it to set a callback that does nothing (except return True if appropriate).

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 Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

method add-child-source ( N-GObject $child_source )

  • N-GObject $child_source; a second Gnome::Glib::Source that source should "poll"

add-poll

Adds a file descriptor to the set of file descriptors polled for this source. This is usually combined with new() to add an event source. The event source's check function will typically test the revents field in the Gnome::Glib::PollFD struct and return True if events need to be processed.

This API is only intended to be used by implementations of Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source 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.

method add-poll ( GPollFD $fd )

  • GPollFD $fd; a Gnome::Glib::PollFD structure holding information about a file descriptor to watch.

add-unix-fd

Monitors fd for the IO events in events.

The tag returned by this function can be used to remove or modify the monitoring of the fd using remove-unix-fd() or g-source-modify-unix-fd().

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 Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

As the name suggests, this function is not available on Windows.

Returns: an opaque tag

method add-unix-fd ( Int $fd, GIOCondition $events --> Pointer )

  • Int $fd; the fd to monitor

  • GIOCondition $events; an event mask

attach

Adds a Gnome::Glib::Source to a context so that it will be executed within that context. Remove it by calling destroy().

Returns: the ID (greater than 0) for the source within the Gnome::Glib::MainContext.

method attach ( N-GObject $context --> UInt )

  • N-GObject $context; a Gnome::Glib::MainContext (if undefined, the default context will be used)

destroy

Removes a source from its Gnome::Glib::MainContext, 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.

method destroy ( )

g-child-watch-add

Sets a function to be called when the child indicated by pid exits, at a default priority, G-PRIORITY-DEFAULT.

If you obtain pid from g-spawn-async() or g-spawn-async-with-pipes() you will need to pass Gnome::Glib::-SPAWN-DO-NOT-REAP-CHILD as flag to the spawn function for the child watching to work.

Note that on platforms where Gnome::Glib::Pid must be explicitly closed (see g-spawn-close-pid()) pid must not be closed while the source is still active. Typically, you will want to call g-spawn-close-pid() in the callback function for the source.

GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for g-child-watch-source-new() apply to this function.

This internally creates a main loop source using g-child-watch-source-new() and attaches it to the main loop context using attach(). You can do these steps manually if you need greater control.

Returns: the ID (greater than 0) of the event source.

method g-child-watch-add ( GPid $pid, GChildWatchFunc $function, Pointer $data --> UInt )

  • GPid $pid; process id to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child).

  • GChildWatchFunc $function; function to call

  • Pointer $data; data to pass to function

g-child-watch-add-full

Sets a function to be called when the child indicated by pid exits, at the priority priority.

If you obtain pid from g-spawn-async() or g-spawn-async-with-pipes() you will need to pass Gnome::Glib::-SPAWN-DO-NOT-REAP-CHILD as flag to the spawn function for the child watching to work.

In many programs, you will want to call g-spawn-check-exit-status() in the callback to determine whether or not the child exited successfully.

Also, note that on platforms where Gnome::Glib::Pid must be explicitly closed (see g-spawn-close-pid()) pid must not be closed while the source is still active. Typically, you should invoke g-spawn-close-pid() in the callback function for the source.

GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for g-child-watch-source-new() apply to this function.

This internally creates a main loop source using g-child-watch-source-new() and attaches it to the main loop context using attach(). You can do these steps manually if you need greater control.

Returns: the ID (greater than 0) of the event source.

method g-child-watch-add-full ( Int $priority, GPid $pid, GChildWatchFunc $function, Pointer $data, GDestroyNotify $notify --> UInt )

  • Int $priority; the priority of the idle source. Typically this will be in the range between G-PRIORITY-DEFAULT-IDLE and G-PRIORITY-HIGH-IDLE.

  • GPid $pid; process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child).

  • GChildWatchFunc $function; function to call

  • Pointer $data; data to pass to function

  • GDestroyNotify $notify; function to call when the idle is removed, or undefined

g-child-watch-source-new

Creates a new child-watch source.

The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with attach() before it will be executed.

Note that child watch sources can only be used in conjunction with `g-spawn...` when the G-SPAWN-DO-NOT-REAP-CHILD flag is used.

Note that on platforms where Gnome::Glib::Pid must be explicitly closed (see g-spawn-close-pid()) pid must not be closed while the source is still active. Typically, you will want to call g-spawn-close-pid() in the callback function for the source.

On POSIX platforms, the following restrictions apply to this API due to limitations in POSIX process interfaces:

* pid must be a child of this process * pid must be positive * the application must not call `waitpid` with a non-positive first argument, for instance in another thread * the application must not wait for pid to exit by any other mechanism, including `waitpid(pid, ...)` or a second child-watch source for the same pid * the application must not ignore SIGCHILD

If any of those conditions are not met, this and related APIs will not work correctly. This can often be diagnosed via a GLib warning stating that `ECHILD` was received by `waitpid`.

Calling `waitpid` for specific processes other than pid remains a valid thing to do.

Returns: the newly-created child watch source

method g-child-watch-source-new ( GPid $pid --> N-GObject )

  • GPid $pid; process to watch. On POSIX the positive pid of a child process. On Windows a handle for a process (which doesn't have to be a child).

g-clear-handle-id

Clears a numeric handler, such as a Gnome::Glib::Source ID.

tag-ptr must be a valid pointer to the variable holding the handler.

If the ID is zero then this function does nothing. Otherwise, clear-func() is called with the ID as a parameter, and the tag is set to zero.

A macro is also included that allows this function to be used without pointer casts.

method g-clear-handle-id ( guInt-ptr $tag_ptr, GClearHandleFunc $clear_func )

  • guInt-ptr $tag_ptr; a pointer to the handler ID

  • GClearHandleFunc $clear_func; the function to call to clear the handler

g-get-current-time

Equivalent to the UNIX gettimeofday() function, but portable.

You may find g-get-real-time() to be more convenient.

method g-get-current-time ( GTimeVal $result )

  • GTimeVal $result; Gnome::Glib::TimeVal structure in which to store current time.

get-monotonic-time

Queries the system monotonic time.

The monotonic clock will always increase and doesn't suffer discontinuities when the user (or NTP) changes the system time. It may or may not continue to tick during times where the machine is suspended.

We try to use the clock that corresponds as closely as possible to the passage of time as measured by system calls such as poll() but it may not always be possible to do this.

Returns: the monotonic time, in microseconds

method get-monotonic-time ( --> Int )

get-real-time

Queries the system wall-clock time.

This call is functionally equivalent to g-get-current-time() except that the return value is often more convenient than dealing with a Gnome::Glib::TimeVal.

You should only use this call if you are actually interested in the real wall-clock time. g-get-monotonic-time() is probably more useful for measuring intervals.

Returns: the number of microseconds since January 1, 1970 UTC.

method get-real-time ( --> Int )

get-can-recurse

Checks whether a source is allowed to be called recursively. see set-can-recurse().

Returns: whether recursion is allowed.

method get-can-recurse ( --> Bool )

get-context

Gets the Gnome::Glib::MainContext with which the source is associated.

You can call this on a source that has been destroyed, provided that the Gnome::Glib::MainContext it was attached to still exists (in which case it will return that Gnome::Glib::MainContext). In particular, you can always call this function on the source returned from g-main-current-source(). But calling this function on a source whose Gnome::Glib::MainContext has been destroyed is an error.

Returns: the Gnome::Glib::MainContext with which the source is associated, or undefined if the context has not yet been added to a source.

method get-context ( --> N-GObject )

get-id

Returns the numeric ID for a particular source. The ID of a source is a positive integer which is unique within a particular main loop context. The reverse mapping from ID to source is done by g-main-context-find-source-by-id().

You can only call this function while the source is associated to a Gnome::Glib::MainContext instance; calling this function before attach() or after g-source-destroy() yields undefined behavior. The ID returned is unique within the Gnome::Glib::MainContext instance passed to g-source-attach().

Returns: the ID (greater than 0) for the source

method get-id ( --> UInt )

get-name

Gets a name for the source, used in debugging and profiling. The name may be NULL if it has never been set with set-name().

Returns: the name of the source

method get-name ( --> Str )

get-priority

Gets the priority of a source.

Returns: the priority of the source

method get-priority ( --> Int )

get-ready-time

Gets the "ready time" of source, as set by set-ready-time().

Any time before the current monotonic time (including 0) is an indication that the source will fire immediately.

Returns: the monotonic ready time, -1 for "never"

method get-ready-time ( --> Int )

get-time

Gets the time to be used when checking this source. The advantage of calling this function over calling g-get-monotonic-time() directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system monotonic time.

The time here is the system monotonic time, if available, or some other reasonable alternative otherwise. See g-get-monotonic-time().

Returns: the monotonic time in microseconds

method get-time ( --> Int )

idle-add

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.

This internally creates a main loop source using g-idle-source-new() and attaches it to the global Gnome::Glib::MainContext using 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.

Returns: the ID (greater than 0) of the event source.

method idle-add (
  Any:D $handler-object, Str:D $method, *%user-options
  --> UInt
)

  • $handler-object; User object where $method is defined

  • Str $method; name of callback handler

  • %user-options; optional named arguments to be provided to the callback

idle-add-full

Adds a function to be called whenever there are no higher priority events pending. If the function returns False it is automatically removed from the list of event sources and will not be called again.

This internally creates a main loop source using g-idle-source-new() and attaches it to the global Gnome::Glib::MainContext using 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.

Returns: the ID (greater than 0) of the event source.

method idle-add-full (
  Int $priority,
  Any:D $handler-object, Str:D $method, Str $method-notify = Str,
  *%user-options
  --> UInt
)

  • Int $priority; the priority of the idle source. Typically this will be in the range between G-PRIORITY-DEFAULT-IDLE and G-PRIORITY-HIGH-IDLE.

  • $handler-object; User object where both methods are defined

  • Str $method; name of callback handler

  • Str $method-notify; name of callback handler. Ignored when $method-notify is undefined. This function is called when the source is removed.

  • %user-options; optional named arguments to be provided to both callbacks

idle-remove-by-data

Removes the idle function with the given data.

Returns: True if an idle source was found and removed.

method idle-remove-by-data ( Pointer $data --> Bool )

  • Pointer $data; the data for the idle source's callback.

g-idle-source-new

Creates a new idle source.

The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with 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.

Returns: the newly-created idle source

method g-idle-source-new ( --> N-GObject )

is-destroyed

Returns whether source has been destroyed.

This is important when you operate upon your objects from within idle handlers, but may have freed the object before the dispatch of your idle handler.

This will fail in a multi-threaded application if the widget is destroyed before the idle handler fires due to the use after free in the callback. A solution, to this particular problem, is to check to if the source has already been destroy within the callback.

Calls to this function from a thread other than the one acquired by the Gnome::Glib::MainContext the Gnome::Glib::Source is attached to are typically redundant, as the source could be destroyed immediately after this function returns. However, once a source is destroyed it cannot be un-destroyed, so this function can be used for opportunistic checks from any thread.

Returns: True if the source has been destroyed

method is-destroyed ( --> Bool )

modify-unix-fd

Updates the event mask to watch for the fd identified by tag.

tag is the tag returned from add-unix-fd().

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 Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

As the name suggests, this function is not available on Windows.

method modify-unix-fd ( Pointer $tag, GIOCondition $new_events )

  • Pointer $tag; the tag from add-unix-fd()

  • GIOCondition $new_events; the new event mask to watch

query-unix-fd

Queries the events reported for the fd corresponding to tag on source during the last poll.

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 Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

As the name suggests, this function is not available on Windows.

Returns: the conditions reported on the fd

method query-unix-fd ( Pointer $tag --> GIOCondition )

  • Pointer $tag; the tag from add-unix-fd()

ref

Increases the reference count on a source by one.

Returns: source

method ref ( --> N-GObject )

remove

Removes the source with the given ID from the default main context. You must use destroy() for sources added to a non-default main context.

The ID of a Gnome::Glib::Source is given by g-source-get-id(), or will be returned by the functions g-source-attach(), g-idle-add(), g-idle-add-full(), g-timeout-add(), g-timeout-add-full(), g-child-watch-add(), g-child-watch-add-full(), g-io-add-watch(), and g-io-add-watch-full().

It is a programmer error to attempt to remove 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.

Returns: For historical reasons, this function always returns True

method remove ( UInt $tag --> Bool )

  • UInt $tag; the ID of the source to remove.

remove-by-funcs-user-data

Removes a source from the default main loop context given the source functions and user data. If multiple sources exist with the same source functions and user data, only one will be destroyed.

Returns: True if a source was found and removed.

method remove-by-funcs-user-data ( N-GSourceFuncs $funcs, Pointer $user_data --> Bool )

  • N-GSourceFuncs $funcs; The source-funcs passed to new()

  • Pointer $user_data; the user data for the callback

remove-by-user-data

Removes a source from the default main loop context given the user data for the callback. If multiple sources exist with the same user data, only one will be destroyed.

Returns: True if a source was found and removed.

method remove-by-user-data ( Pointer $user_data --> Bool )

  • Pointer $user_data; the user-data for the callback.

remove-child-source

Detaches child-source from source and destroys it.

This API is only intended to be used by implementations of Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

method remove-child-source ( N-GObject $child_source )

  • N-GObject $child_source; a Gnome::Glib::Source previously passed to add-child-source().

remove-poll

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 Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

method remove-poll ( GPollFD $fd )

  • GPollFD $fd; a Gnome::Glib::PollFD structure previously passed to add-poll().

remove-unix-fd

Reverses the effect of a previous call to add-unix-fd().

You only need to call this if you want to remove an fd from being 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 Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

As the name suggests, this function is not available on Windows.

method remove-unix-fd ( Pointer $tag )

  • Pointer $tag; the tag from add-unix-fd()

set-callback

Sets the callback function for a source. The callback for a source is called from the source's dispatch function.

Typically, you won't use this function. Instead use functions specific to the type of source you are using, such as g-idle-add() or g-timeout-add().

It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns.

method set-callback (
  Any:D $handler-object, Str:D $method, Str $method-notify = Str,
  *%user-options
)

  • $handler-object; User object where both methods are defined

  • Str $method; name of callback handler

  • Str $method-notify; name of callback handler. Ignored when $method-notify is undefined. This function is called when the source is removed.

  • %user-options; optional named arguments to be provided to both callbacks

set-callback-indirect

Sets the callback function storing the data as a refcounted callback "object". This is used internally. Note that calling set-callback-indirect() assumes an initial reference count on callback-data, and thus callback-funcs->unref will eventually be called once more than callback-funcs->ref.

It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns.

method set-callback-indirect ( Pointer $callback_data, N-GObjectCallbackFuncs $callback_funcs )

  • Pointer $callback_data; pointer to callback data "object"

  • N-GObjectCallbackFuncs $callback_funcs; functions for reference counting callback-data and getting the callback and data

set-can-recurse

Sets whether a source can be called recursively. If can-recurse is True, then while the source is being dispatched then this source will be processed normally. Otherwise, all processing of this source is blocked until the dispatch function returns.

method set-can-recurse ( Bool $can_recurse )

  • Bool $can_recurse; whether recursion is allowed for this source

set-funcs

Sets the source functions (can be used to override default implementations) of an unattached source.

method set-funcs ( N-GSourceFuncs $funcs )

  • N-GSourceFuncs $funcs; the new Gnome::Glib::SourceFuncs

set-name

Sets a name for the source, used in debugging and profiling. The name defaults to NULL.

The source name should describe in a human-readable way what the source does. For example, "X11 event queue" or "GTK+ repaint idle handler" or whatever it is.

It is permitted to call this function multiple times, but is not recommended due to the potential performance impact. For example, one could change the name in the "check" function of a Gnome::Glib::SourceFuncs to include details like the event type in the source name.

Use caution if changing the name while another thread may be accessing it with get-name(); that function does not copy the value, and changing the value will free it while the other thread may be attempting to use it.

method set-name ( Str $name )

  • Str $name; debug name for the source

set-name-by-id

Sets the name of a source using its ID.

This is a convenience utility to set source names from the return value of g-idle-add(), timeout-add(), etc.

It is a programmer error to attempt to set the name of 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.

method set-name-by-id ( UInt $tag, Str $name )

  • UInt $tag; a Gnome::Glib::Source ID

  • Str $name; debug name for the source

set-priority

Sets the priority of a source. 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.

method set-priority ( Int $priority )

  • Int $priority; the new priority.

set-ready-time

Sets a Gnome::Glib::Source to be dispatched when the given monotonic time is reached (or passed). If the monotonic time is in the past (as it always will be if ready-time is 0) then the source will be dispatched immediately.

If ready-time is -1 then the source is never woken up on the basis of the passage of time.

Dispatching the source does not reset the ready time. You should do so yourself, from the source dispatch function.

Note that if you have a pair of sources where the ready time of one suggests that it will be delivered first but the priority for the other suggests that it would be delivered first, and the ready time for both sources is reached during the same main context iteration, then the order of dispatch is undefined.

It is a no-op to call this function on a Gnome::Glib::Source which has already been destroyed with destroy().

This API is only intended to be used by implementations of Gnome::Glib::Source. Do not call this API on a Gnome::Glib::Source that you did not create.

method set-ready-time ( Int $ready_time )

  • Int $ready_time; the monotonic time at which the source will be ready, 0 for "immediately", -1 for "never"

timeout-add

Sets a function to be called at regular intervals, with the default priority, G-PRIORITY-DEFAULT. 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 first call to the function will be at the end of the first $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).

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 timeout-add-seconds() function; this function allows for more optimizations and more efficient system power usage.

The interval given is in terms of monotonic time, not wall clock time. See get-monotonic-time().

Returns: the ID (greater than 0) of the event source.

method timeout-add (
  UInt $interval,
  Any:D $handler-object, Str:D $method, *%user-options
  --> UInt
)

  • UInt $interval; the time between calls to the function, in milliseconds (1/1000ths of a second)

  • $handler-object; User object where $method is defined

  • Str $method; name of callback handler

  • %user-options; optional named arguments to be provided to the callback

timeout-add-full

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.

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).

This internally creates a main loop source using g-timeout-source-new() and attaches it to the global Gnome::Glib::MainContext using 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.

The interval given is in terms of monotonic time, not wall clock time. See g-get-monotonic-time().

Returns: the ID (greater than 0) of the event source.

method timeout-add-full (
  Int $priority, UInt $interval,
  Any:D $handler-object, Str:D $method, Str $method-notify = Str,
  *%user-options
  --> UInt
)

  • Int $priority; the priority of the timeout source. Typically this will be in the range between G-PRIORITY-DEFAULT and G-PRIORITY-HIGH.

  • UInt $interval; the time between calls to the function, in milliseconds (1/1000ths of a second)

  • $handler-object; User object where both methods are defined

  • Str $method; name of callback handler

  • Str $method-notify; name of callback handler. Ignored when $method-notify is undefined. This function is called when the source is removed.

  • %user-options; optional named arguments to be provided to both callbacks

timeout-add-seconds

Sets a function to be called at regular intervals with the default priority, G-PRIORITY-DEFAULT. 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.

This internally creates a main loop source using g-timeout-source-new-seconds() and attaches it to the main loop context using attach(). You can do these steps manually if you need greater control. Also see timeout-add-seconds-full().

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 timeout-add() instead.

The interval given is in terms of monotonic time, not wall clock time. See g-get-monotonic-time().

Returns: the ID (greater than 0) of the event source.

method timeout-add-seconds (
  UInt $interval, Any:D $handler-object, Str:D $method, *%user-options
  --> UInt
)

  • UInt $interval; the time between calls to the function, in seconds

  • $handler-object; User object where $method is defined

  • Str $method; name of callback handler

  • %user-options; optional named arguments to be provided to the callback

timeout-add-seconds-full

Sets a function to be called at regular intervals, with 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.

Unlike 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.

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

If you want timing more precise than whole seconds, use timeout-add() instead.

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 timeout-add-seconds() is preferred over timeout-add().

This internally creates a main loop source using timeout-source-new-seconds() and attaches it to the main loop context using attach(). You can do these steps manually if you need greater control.

The interval given is in terms of monotonic time, not wall clock time. See get-monotonic-time().

Returns: the ID (greater than 0) of the event source.

method timeout-add-seconds-full (
  Int $priority, UInt $interval,
  Any:D $handler-object, Str:D $method, Str $method-notify = Str,
  *%user-options
  --> UInt
)

  • Int $priority; the priority of the timeout source. Typically this will be in the range between G-PRIORITY-DEFAULT and G-PRIORITY-HIGH.

  • UInt $interval; the time between calls to the function, in seconds

  • $handler-object; User object where both methods are defined

  • Str $method; name of callback handler

  • Str $method-notify; name of callback handler. Ignored when $method-notify is undefined. This function is called when the source is removed.

  • %user-options; optional named arguments to be provided to both callbacks

g-timeout-source-new

Creates a new timeout source.

The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with attach() before it will be executed.

The interval given is in terms of monotonic time, not wall clock time. See g-get-monotonic-time().

Returns: the newly-created timeout source

method g-timeout-source-new ( UInt $interval --> N-GObject )

  • UInt $interval; the timeout interval in milliseconds.

g-timeout-source-new-seconds

Creates a new timeout source.

The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with attach() before it will be executed.

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().

Returns: the newly-created timeout source

method g-timeout-source-new-seconds ( UInt $interval --> N-GObject )

  • UInt $interval; the timeout interval in seconds

unref

Decreases the reference count of a source by one. If the resulting reference count is zero the source and associated memory will be destroyed.

method unref ( )

_g_source_new

Creates a new Gnome::Glib::Source structure. The size is specified to allow creating structures derived from Gnome::Glib::Source that contain additional data. The size passed in must be at least `sizeof (N-GObject)`.

The source will not initially be associated with any Gnome::Glib::MainContext and must be added to one with attach() before it will be executed.

Returns: the newly-created Gnome::Glib::Source.

method _g_source_new ( N-GSourceFuncs $source_funcs, UInt $struct_size --> N-GObject )

  • N-GSourceFuncs $source_funcs; structure containing functions that implement the sources behavior.

  • UInt $struct_size; size of the Gnome::Glib::Source structure to create.