Callbacks

CacheDestroyFunc (value)

CacheDupFunc (value)

CacheNewFunc (key)

ChildWatchFunc (pid, wait_status, *user_data)

ClearHandleFunc (handle_id)

CompareDataFunc (a, b, *user_data)

CompareFunc (a, b)

CompletionFunc (item)

CompletionStrncmpFunc (s1, s2, n)

CopyFunc (src, data)

DataForeachFunc (key_id, data, *user_data)

DestroyNotify (data)

DuplicateFunc (data, *user_data)

EqualFunc (a, b)

EqualFuncFull (a, b, *user_data)

ErrorClearFunc (error)

ErrorCopyFunc (src_error, dest_error)

ErrorInitFunc (error)

FreeFunc (data)

Func (data, *user_data)

HFunc (key, value, *user_data)

HRFunc (key, value, *user_data)

HashFunc (key)

HookCheckFunc (data)

HookCheckMarshaller (hook, marshal_data)

HookCompareFunc (new_hook, sibling)

HookFinalizeFunc (hook_list, hook)

HookFindFunc (hook, data)

HookFunc (data)

HookMarshaller (hook, marshal_data)

IOFunc (source, condition, data)

LogFunc (log_domain, log_level, message, *user_data)

LogWriterFunc (log_level, fields, *user_data)

NodeForeachFunc (node, data)

NodeTraverseFunc (node, data)

OptionArgFunc (option_name, value, data)

OptionErrorFunc (context, group, data)

OptionParseFunc (context, group, data)

PollFunc (ufds, nfsd, timeout_)

PrintFunc (string)

RegexEvalCallback (match_info, result, *user_data)

ScannerMsgFunc (scanner, message, error)

SequenceIterCompareFunc (a, b, data)

SourceDisposeFunc (source)

SourceDummyMarshal ()

SourceFunc (*user_data)

SourceOnceFunc (*user_data)

SpawnChildSetupFunc (data)

TestDataFunc (*user_data)

TestFixtureFunc (fixture, *user_data)

TestFunc ()

TestLogFatalFunc (log_domain, log_level, message, *user_data)

ThreadFunc (data)

TranslateFunc (str, data)

TraverseFunc (key, value, data)

TraverseNodeFunc (node, data)

UnixFDSourceFunc (fd, condition, *user_data)

VoidFunc ()

Details

GLib.CacheDestroyFunc(value)
Parameters:

value (object or None) – the GLib.Cache value to destroy

Specifies the type of the value_destroy_func and key_destroy_func functions passed to g_cache_new(). The functions are passed a pointer to the GLib.Cache key or GLib.Cache value and should free any memory and other resources associated with it.

Deprecated since version 2.32: Use a GLib.HashTable instead

GLib.CacheDupFunc(value)
Parameters:

value (object or None) – the GLib.Cache key to destroy (__not__ a GLib.Cache value as it seems)

Returns:

a copy of the GLib.Cache key

Return type:

object or None

Specifies the type of the key_dup_func function passed to g_cache_new(). The function is passed a key (__not__ a value as the prototype implies) and should return a duplicate of the key.

Deprecated since version 2.32: Use a GLib.HashTable instead

GLib.CacheNewFunc(key)
Parameters:

key (object or None) – a GLib.Cache key

Returns:

a new GLib.Cache value corresponding to the key.

Return type:

object or None

Specifies the type of the value_new_func function passed to g_cache_new(). It is passed a GLib.Cache key and should create the value corresponding to the key.

Deprecated since version 2.32: Use a GLib.HashTable instead

GLib.ChildWatchFunc(pid, wait_status, *user_data)
Parameters:

  • pid (int) – the process id of the child process

  • wait_status (int) – Status information about the child process, encoded in a platform-specific manner

  • user_data (object or None) – user data passed to GLib.child_watch_add()

Prototype of a #GChildWatchSource callback, called when a child process has exited.

To interpret wait_status, see the documentation for GLib.spawn_check_wait_status(). In particular, on Unix platforms, note that it is usually not equal to the integer passed to exit() or returned from main().

GLib.ClearHandleFunc(handle_id)
Parameters:

handle_id (int) – the handle ID to clear

Specifies the type of function passed to g_clear_handle_id(). The implementation is expected to free the resource identified by handle_id; for instance, if handle_id is a GLib.Source ID, GLib.Source.remove() can be used.

New in version 2.56.

GLib.CompareDataFunc(a, b, *user_data)
Parameters:
Returns:

negative value if a < b; zero if a = b; positive value if a > b

Return type:

int

Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second.

GLib.CompareFunc(a, b)
Parameters:
Returns:

negative value if a < b; zero if a = b; positive value if a > b

Return type:

int

Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second.

GLib.CompletionFunc(item)
Parameters:

item (object or None) – the completion item.

Returns:

the string corresponding to the item.

Return type:

str

Specifies the type of the function passed to g_completion_new(). It should return the string corresponding to the given target item. This is used when you use data structures as GLib.Completion items.

Deprecated since version 2.26: Rarely used API

GLib.CompletionStrncmpFunc(s1, s2, n)
Parameters:

  • s1 (str) – string to compare with s2.

  • s2 (str) – string to compare with s1.

  • n (int) – maximal number of bytes to compare.

Returns:

an integer less than, equal to, or greater than zero if the first n bytes of s1 is found, respectively, to be less than, to match, or to be greater than the first n bytes of s2.

Return type:

int

Specifies the type of the function passed to g_completion_set_compare(). This is used when you use strings as GLib.Completion items.

Deprecated since version 2.26: Rarely used API

GLib.CopyFunc(src, data)
Parameters:

  • src (object) – A pointer to the data which should be copied

  • data (object or None) – Additional data

Returns:

A pointer to the copy

Return type:

object

A function of this signature is used to copy the node data when doing a deep-copy of a tree.

New in version 2.4.

GLib.DataForeachFunc(key_id, data, *user_data)
Parameters:

Specifies the type of function passed to GLib.dataset_foreach(). It is called with each #GQuark id and associated data element, together with the user_data parameter supplied to GLib.dataset_foreach().

GLib.DestroyNotify(data)
Parameters:

data (object or None) – the data element.

Specifies the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it.

GLib.DuplicateFunc(data, *user_data)
Parameters:

  • data (object or None) – the data to duplicate

  • user_data (object or None) – user data that was specified in g_datalist_id_dup_data()

Returns:

a duplicate of data

Return type:

object or None

The type of functions that are used to ‘duplicate’ an object. What this means depends on the context, it could just be incrementing the reference count, if data is a ref-counted object.

GLib.EqualFunc(a, b)
Parameters:
Returns:

True if a = b; False otherwise

Return type:

bool

Specifies the type of a function used to test two values for equality. The function should return True if both values are equal and False otherwise.

GLib.EqualFuncFull(a, b, *user_data)
Parameters:
Returns:

True if a = b; False otherwise

Return type:

bool

Specifies the type of a function used to test two values for equality. The function should return True if both values are equal and False otherwise.

This is a version of GLib.EqualFunc which provides a user_data closure from the caller.

New in version 2.74.

GLib.ErrorClearFunc(error)
Parameters:

error (GLib.Error) – extended error to clear

Specifies the type of function which is called when an extended error instance is freed. It is passed the error pointer about to be freed, and should free the error’s private data fields.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from error.

New in version 2.68.

GLib.ErrorCopyFunc(src_error, dest_error)
Parameters:

  • src_error (GLib.Error) – source extended error

  • dest_error (GLib.Error) – destination extended error

Specifies the type of function which is called when an extended error instance is copied. It is passed the pointer to the destination error and source error, and should copy only the fields of the private data from src_error to dest_error.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from src_error and dest_error.

New in version 2.68.

GLib.ErrorInitFunc(error)
Parameters:

error (GLib.Error) – extended error

Specifies the type of function which is called just after an extended error instance is created and its fields filled. It should only initialize the fields in the private data, which can be received with the generated *_get_private() function.

Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it already takes care of getting the private data from error.

New in version 2.68.

GLib.FreeFunc(data)
Parameters:

data (object or None) – a data pointer

Declares a type of function which takes an arbitrary data pointer argument and has no return value. It is not currently used in GLib or GTK.

GLib.Func(data, *user_data)
Parameters:

  • data (object or None) – the element’s data

  • user_data (object or None) – user data passed to g_list_foreach() or g_slist_foreach()

Specifies the type of functions passed to g_list_foreach() and g_slist_foreach().

GLib.HFunc(key, value, *user_data)
Parameters:

Specifies the type of the function passed to GLib.HashTable.foreach(). It is called with each key/value pair, together with the user_data parameter which is passed to GLib.HashTable.foreach().

GLib.HRFunc(key, value, *user_data)
Parameters:
Returns:

True if the key/value pair should be removed from the GLib.HashTable

Return type:

bool

Specifies the type of the function passed to GLib.HashTable.foreach_remove(). It is called with each key/value pair, together with the user_data parameter passed to GLib.HashTable.foreach_remove(). It should return True if the key/value pair should be removed from the GLib.HashTable.

GLib.HashFunc(key)
Parameters:

key (object or None) – a key

Returns:

the hash value corresponding to the key

Return type:

int

Specifies the type of the hash function which is passed to g_hash_table_new() when a GLib.HashTable is created.

The function is passed a key and should return a int hash value. The functions GLib.direct_hash(), GLib.int_hash() and GLib.str_hash() provide hash functions which can be used when the key is a object, int, and str respectively.

GLib.direct_hash() is also the appropriate hash function for keys of the form GINT_TO_POINTER (n) (or similar macros).

A good hash functions should produce hash values that are evenly distributed over a fairly large range. The modulus is taken with the hash table size (a prime number) to find the ‘bucket’ to place each key into. The function should also be very fast, since it is called for each key lookup.

Note that the hash functions provided by GLib have these qualities, but are not particularly robust against manufactured keys that cause hash collisions. Therefore, you should consider choosing a more secure hash function when using a GLib.HashTable with keys that originate in untrusted data (such as HTTP requests). Using GLib.str_hash() in that situation might make your application vulnerable to Algorithmic Complexity Attacks.

The key to choosing a good hash is unpredictability. Even cryptographic hashes are very easy to find collisions for when the remainder is taken modulo a somewhat predictable prime number. There must be an element of randomness that an attacker is unable to guess.

GLib.HookCheckFunc(data)
Parameters:

data (object or None) – the data field of the GLib.Hook is passed to the hook function here

Returns:

False if the GLib.Hook should be destroyed

Return type:

bool

Defines the type of a hook function that can be invoked by GLib.HookList.invoke_check().

GLib.HookCheckMarshaller(hook, marshal_data)
Parameters:
Returns:

False if hook should be destroyed

Return type:

bool

Defines the type of function used by GLib.HookList.marshal_check().

GLib.HookCompareFunc(new_hook, sibling)
Parameters:
Returns:

a value <= 0 if new_hook should be before sibling

Return type:

int

Defines the type of function used to compare GLib.Hook elements in GLib.Hook.insert_sorted().

GLib.HookFinalizeFunc(hook_list, hook)
Parameters:

Defines the type of function to be called when a hook in a list of hooks gets finalized.

GLib.HookFindFunc(hook, data)
Parameters:
Returns:

True if the required GLib.Hook has been found

Return type:

bool

Defines the type of the function passed to g_hook_find().

GLib.HookFunc(data)
Parameters:

data (object or None) – the data field of the GLib.Hook is passed to the hook function here

Defines the type of a hook function that can be invoked by GLib.HookList.invoke().

GLib.HookMarshaller(hook, marshal_data)
Parameters:

Defines the type of function used by GLib.HookList.marshal().

GLib.IOFunc(source, condition, data)
Parameters:
Returns:

the function should return False if the event source should be removed

Return type:

bool

Specifies the type of function passed to GLib.io_add_watch() or GLib.io_add_watch(), which is called when the requested condition on a GLib.IOChannel is satisfied.

GLib.LogFunc(log_domain, log_level, message, *user_data)
Parameters:

  • log_domain (str) – the log domain of the message

  • log_level (GLib.LogLevelFlags) – the log level of the message (including the fatal and recursion flags)

  • message (str) – the message to process

  • user_data (object or None) – user data, set in [func`GLib`.log_set_handler]

Specifies the prototype of log handler functions.

The default log handler, [func`GLib`.log_default_handler], automatically appends a new-line character to message when printing it. It is advised that any custom log handler functions behave similarly, so that logging calls in user code do not need modifying to add a new-line character to the message if the log handler is changed.

This is not used if structured logging is enabled; see Using Structured Logging.

GLib.LogWriterFunc(log_level, fields, *user_data)
Parameters:
Returns:

GLib.LogWriterOutput.HANDLED if the log entry was handled successfully; GLib.LogWriterOutput.UNHANDLED otherwise

Return type:

GLib.LogWriterOutput

Writer function for log entries. A log entry is a collection of one or more GLib.LogFields, using the standard field names from journal specification. See g_log_structured() for more information.

Writer functions must ignore fields which they do not recognise, unless they can write arbitrary binary output, as field values may be arbitrary binary.

log_level is guaranteed to be included in fields as the PRIORITY field, but is provided separately for convenience of deciding whether or where to output the log entry.

Writer functions should return GLib.LogWriterOutput.HANDLED if they handled the log message successfully or if they deliberately ignored it. If there was an error handling the message (for example, if the writer function is meant to send messages to a remote logging server and there is a network error), it should return GLib.LogWriterOutput.UNHANDLED. This allows writer functions to be chained and fall back to simpler handlers in case of failure.

New in version 2.50.

GLib.NodeForeachFunc(node, data)
Parameters:

Specifies the type of function passed to GLib.Node.children_foreach(). The function is called with each child node, together with the user data passed to GLib.Node.children_foreach().

GLib.NodeTraverseFunc(node, data)
Parameters:
Returns:

True to stop the traversal.

Return type:

bool

Specifies the type of function passed to GLib.Node.traverse(). The function is called with each of the nodes visited, together with the user data passed to GLib.Node.traverse(). If the function returns True, then the traversal is stopped.

GLib.OptionArgFunc(option_name, value, data)
Parameters:

  • option_name (str) – The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name.

  • value (str) – The value to be parsed.

  • data (object or None) – User data added to the GLib.OptionGroup containing the option when it was created with GLib.OptionGroup.new()

Returns:

True if the option was successfully parsed, False if an error occurred, in which case error should be set with g_set_error()

Return type:

bool

The type of function to be passed as callback for GLib.OptionArg.CALLBACK options.

GLib.OptionErrorFunc(context, group, data)
Parameters:

The type of function to be used as callback when a parse error occurs.

GLib.OptionParseFunc(context, group, data)
Parameters:
Returns:

True if the function completed successfully, False if an error occurred, in which case error should be set with g_set_error()

Return type:

bool

The type of function that can be called before and after parsing.

GLib.PollFunc(ufds, nfsd, timeout_)
Parameters:

  • ufds (GLib.PollFD) – an array of GLib.PollFD elements

  • nfsd (int) – the number of elements in ufds

  • timeout (int) – the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout.

Returns:

the number of GLib.PollFD elements which have events or errors reported, or -1 if an error occurred.

Return type:

int

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.

GLib.PrintFunc(string)
Parameters:

string (str) – the message to output

Specifies the type of the print handler functions. These are called with the complete formatted string to output.

GLib.RegexEvalCallback(match_info, result, *user_data)
Parameters:
Returns:

False to continue the replacement process, True to stop it

Return type:

bool

Specifies the type of the function passed to GLib.Regex.replace_eval(). It is called for each occurrence of the pattern in the string passed to GLib.Regex.replace_eval(), and it should append the replacement to result.

New in version 2.14.

GLib.ScannerMsgFunc(scanner, message, error)
Parameters:

Specifies the type of the message handler function.

GLib.SequenceIterCompareFunc(a, b, data)
Parameters:
Returns:

zero if the iterators are equal, a negative value if a comes before b, and a positive value if b comes before a.

Return type:

int

A GLib.SequenceIterCompareFunc is a function used to compare iterators. It must return zero if the iterators compare equal, a negative value if a comes before b, and a positive value if b comes before a.

GLib.SourceDisposeFunc(source)
Parameters:

source (GLib.Source) – GLib.Source that is currently being disposed

Dispose function for source. See g_source_set_dispose_function() for details.

New in version 2.64.

GLib.SourceDummyMarshal()

This is just a placeholder for #GClosureMarshal, which cannot be used here for dependency reasons.

GLib.SourceFunc(*user_data)
Parameters:

user_data (object or None) – data passed to the function, set when the source was created with one of the above functions

Returns:

False if the source should be removed. GLib.SOURCE_CONTINUE and GLib.SOURCE_REMOVE are more memorable names for the return value.

Return type:

bool

Specifies the type of function passed to GLib.timeout_add(), GLib.timeout_add(), GLib.idle_add(), and GLib.idle_add().

When calling GLib.Source.set_callback(), you may need to cast a function of a different type to this type. Use G_SOURCE_FUNC() to avoid warnings about incompatible function types.

GLib.SourceOnceFunc(*user_data)
Parameters:

user_data (object or None) – data passed to the function, set when the source was created

A source function that is only called once before being removed from the main context automatically.

See: g_idle_add_once(), g_timeout_add_once()

New in version 2.74.

GLib.SpawnChildSetupFunc(data)
Parameters:

data (object or None) – user data passed to the function.

Specifies the type of the setup function passed to GLib.spawn_async(), GLib.spawn_sync() and GLib.spawn_async_with_pipes(), which can, in very limited ways, be used to affect the child’s execution.

On POSIX platforms, the function is called in the child after GLib has performed all the setup it plans to perform, but before calling exec(). Actions taken in this function will only affect the child, not the parent.

On Windows, the function is called in the parent. Its usefulness on Windows is thus questionable. In many cases executing the child setup function in the parent can have ill effects, and you should be very careful when porting software to Windows that uses child setup functions.

However, even on POSIX, you are extremely limited in what you can safely do from a GLib.SpawnChildSetupFunc, because any mutexes that were held by other threads in the parent process at the time of the fork() will still be locked in the child process, and they will never be unlocked (since the threads that held them don’t exist in the child). POSIX allows only async-signal-safe functions (see signal(7)) to be called in the child between fork() and exec(), which drastically limits the usefulness of child setup functions.

In particular, it is not safe to call any function which may call malloc(), which includes POSIX functions such as setenv(). If you need to set up the child environment differently from the parent, you should use GLib.get_environ(), GLib.environ_setenv(), and GLib.environ_unsetenv(), and then pass the complete environment list to the g_spawn... function.

GLib.TestDataFunc(*user_data)
Parameters:

user_data (object or None) – the data provided when registering the test

The type used for test case functions that take an extra pointer argument.

New in version 2.28.

GLib.TestFixtureFunc(fixture, *user_data)
Parameters:

  • fixture (object) – the test fixture

  • user_data (object or None) – the data provided when registering the test

The type used for functions that operate on test fixtures. This is used for the fixture setup and teardown functions as well as for the testcases themselves.

user_data is a pointer to the data that was given when registering the test case.

fixture will be a pointer to the area of memory allocated by the test framework, of the size requested. If the requested size was zero then fixture will be equal to user_data.

New in version 2.28.

GLib.TestFunc()

The type used for test case functions.

New in version 2.28.

GLib.TestLogFatalFunc(log_domain, log_level, message, *user_data)
Parameters:

  • log_domain (str) – the log domain of the message

  • log_level (GLib.LogLevelFlags) – the log level of the message (including the fatal and recursion flags)

  • message (str) – the message to process

  • user_data (object or None) – user data, set in g_test_log_set_fatal_handler()

Returns:

True if the program should abort, False otherwise

Return type:

bool

Specifies the prototype of fatal log handler functions.

New in version 2.22.

GLib.ThreadFunc(data)
Parameters:

data (object or None) – data passed to the thread

Returns:

the return value of the thread

Return type:

object or None

Specifies the type of the func functions passed to GLib.Thread.new() or GLib.Thread.try_new().

GLib.TranslateFunc(str, data)
Parameters:
Returns:

a translation of the string for the current locale. The returned string is owned by GLib and must not be freed.

Return type:

str

The type of functions which are used to translate user-visible strings, for –help output.

GLib.TraverseFunc(key, value, data)
Parameters:
Returns:

True to stop the traversal

Return type:

bool

Specifies the type of function passed to GLib.Tree.traverse(). It is passed the key and value of each node, together with the user_data parameter passed to GLib.Tree.traverse(). If the function returns True, the traversal is stopped.

GLib.TraverseNodeFunc(node, data)
Parameters:
Returns:

True to stop the traversal

Return type:

bool

Specifies the type of function passed to GLib.Tree.foreach_node(). It is passed each node, together with the user_data parameter passed to GLib.Tree.foreach_node(). If the function returns True, the traversal is stopped.

New in version 2.68.

GLib.UnixFDSourceFunc(fd, condition, *user_data)
Parameters:

  • fd (int) – the fd that triggered the event

  • condition (GLib.IOCondition) – the IO conditions reported on fd

  • user_data (object or None) – user data passed to g_unix_fd_add()

Returns:

False if the source should be removed

Return type:

bool

The type of functions to be called when a UNIX fd watch source triggers.

GLib.VoidFunc()

Declares a type of function which takes no arguments and has no return value. It is used to specify the type function passed to GLib.atexit().