string_chunks.sgml
thread_pools.sgml
threads.sgml
+trees-binary.sgml
+trees-nary.sgml
timers.sgml
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-Balanced Binary Trees
-
-<!-- ##### SECTION Short_Description ##### -->
-a sorted collection of key/value pairs optimized for searching
-and traversing in order
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GTree structure and its associated functions provide a sorted collection
-of key/value pairs optimized for searching and traversing in order.
-</para>
-<para>
-To create a new #GTree use g_tree_new().
-</para>
-<para>
-To insert a key/value pair into a #GTree use g_tree_insert().
-</para>
-<para>
-To lookup the value corresponding to a given key, use g_tree_lookup() and
-g_tree_lookup_extended().
-</para>
-<para>
-To find out the number of nodes in a #GTree, use g_tree_nnodes().
-To get the height of a #GTree, use g_tree_height().
-</para>
-<para>
-To traverse a #GTree, calling a function for each node visited in the
-traversal, use g_tree_foreach().
-</para>
-<para>
-To remove a key/value pair use g_tree_remove().
-</para>
-<para>
-To destroy a #GTree, use g_tree_destroy().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GTree ##### -->
-<para>
-The <structname>GTree</structname> struct is an opaque data structure representing a
-<link linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
-It should be accessed only by using the following functions.
-</para>
-
-
-<!-- ##### FUNCTION g_tree_new ##### -->
-<para>
-
-</para>
-
-@key_compare_func:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_ref ##### -->
-<para>
-
-</para>
-
-@tree:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_unref ##### -->
-<para>
-
-</para>
-
-@tree:
-
-
-<!-- ##### FUNCTION g_tree_new_with_data ##### -->
-<para>
-
-</para>
-
-@key_compare_func:
-@key_compare_data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_new_full ##### -->
-<para>
-
-</para>
-
-@key_compare_func:
-@key_compare_data:
-@key_destroy_func:
-@value_destroy_func:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_insert ##### -->
-<para>
-
-</para>
-
-@tree:
-@key:
-@value:
-
-
-<!-- ##### FUNCTION g_tree_replace ##### -->
-<para>
-
-</para>
-
-@tree:
-@key:
-@value:
-
-
-<!-- ##### FUNCTION g_tree_nnodes ##### -->
-<para>
-
-</para>
-
-@tree:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_height ##### -->
-<para>
-
-</para>
-
-@tree:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_lookup ##### -->
-<para>
-
-</para>
-
-@tree:
-@key:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_lookup_extended ##### -->
-
-
-@tree:
-@lookup_key:
-@orig_key:
-@value:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_foreach ##### -->
-<para>
-
-</para>
-
-@tree:
-@func:
-@user_data:
-
-
-<!-- ##### FUNCTION g_tree_traverse ##### -->
-<para>
-
-</para>
-
-@tree:
-@traverse_func:
-@traverse_type:
-@user_data:
-
-
-<!-- ##### USER_FUNCTION GTraverseFunc ##### -->
-<para>
-Specifies the type of function passed to g_tree_traverse().
-It is passed the key and value of each node, together with
-the @user_data parameter passed to g_tree_traverse().
-If the function returns %TRUE, the traversal is stopped.
-</para>
-
-@key: a key of a #GTree node.
-@value: the value corresponding to the key.
-@data: user data passed to g_tree_traverse().
-@Returns: %TRUE to stop the traversal.
-
-
-<!-- ##### ENUM GTraverseType ##### -->
-<para>
-Specifies the type of traveral performed by g_tree_traverse(),
-g_node_traverse() and g_node_find().
-</para>
-
-@G_IN_ORDER: vists a node's left child first, then the node itself, then its
- right child. This is the one to use if you want the output sorted according
- to the compare function.
-@G_PRE_ORDER: visits a node, then its children.
-@G_POST_ORDER: visits the node's children, then the node itself.
-@G_LEVEL_ORDER: is not implemented for
- <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>.
- For <link linkend="glib-N-ary-Trees">N-ary Trees</link>, it vists the root
- node first, then its children, then its grandchildren, and so on. Note that
- this is less efficient than the other orders.
-
-<!-- ##### FUNCTION g_tree_search ##### -->
-<para>
-
-</para>
-
-@tree:
-@search_func:
-@user_data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_remove ##### -->
-<para>
-
-</para>
-
-@tree:
-@key:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_steal ##### -->
-<para>
-
-</para>
-
-@tree:
-@key:
-@Returns:
-
-
-<!-- ##### FUNCTION g_tree_destroy ##### -->
-<para>
-
-</para>
-
-@tree:
-
-
+++ /dev/null
-<!-- ##### SECTION Title ##### -->
-N-ary Trees
-
-<!-- ##### SECTION Short_Description ##### -->
-trees of data with any number of branches
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GNode struct and its associated functions provide a N-ary tree data
-structure, where nodes in the tree can contain arbitrary data.
-</para>
-<para>
-To create a new tree use g_node_new().
-</para>
-<para>
-To insert a node into a tree use g_node_insert(), g_node_insert_before(),
-g_node_append() and g_node_prepend().
-</para>
-<para>
-To create a new node and insert it into a tree use g_node_insert_data(),
-g_node_insert_data_before(), g_node_append_data() and g_node_prepend_data().
-</para>
-<para>
-To reverse the children of a node use g_node_reverse_children().
-</para>
-<para>
-To find a node use g_node_get_root(), g_node_find(), g_node_find_child(),
-g_node_child_index(), g_node_child_position(),
-g_node_first_child(), g_node_last_child(),
-g_node_nth_child(), g_node_first_sibling(), g_node_prev_sibling(),
-g_node_next_sibling() or g_node_last_sibling().
-</para>
-<para>
-To get information about a node or tree use G_NODE_IS_LEAF(),
-G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), g_node_n_children(),
-g_node_is_ancestor() or g_node_max_height().
-</para>
-<para>
-To traverse a tree, calling a function for each node visited in the
-traversal, use g_node_traverse() or g_node_children_foreach().
-</para>
-<para>
-To remove a node or subtree from a tree use g_node_unlink() or
-g_node_destroy().
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GNode ##### -->
-<para>
-The <structname>GNode</structname> struct represents one node in a
-<link linkend="glib-N-ary-Trees">N-ary Tree</link>.
-fields
-</para>
-
-@data: contains the actual data of the node.
-@next: points to the node's next sibling (a sibling is another
- <structname>GNode</structname> with the same parent).
-@prev: points to the node's previous sibling.
-@parent: points to the parent of the <structname>GNode</structname>,
- or is %NULL if the <structname>GNode</structname> is the root of the tree.
-@children: The <structfield>children</structfield> field points to the first
- child of the <structname>GNode</structname>. The other children are accessed
- by using the <structfield>next</structfield> pointer of each child.
-
-<!-- ##### FUNCTION g_node_new ##### -->
-<para>
-
-</para>
-
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_copy ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### USER_FUNCTION GCopyFunc ##### -->
-<para>
-
-</para>
-
-@src:
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_copy_deep ##### -->
-<para>
-
-</para>
-
-@node:
-@copy_func:
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_insert ##### -->
-<para>
-
-</para>
-
-@parent:
-@position:
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_insert_before ##### -->
-<para>
-
-</para>
-
-@parent:
-@sibling:
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_insert_after ##### -->
-<para>
-
-</para>
-
-@parent:
-@sibling:
-@node:
-@Returns:
-
-
-<!-- ##### MACRO g_node_append ##### -->
-<para>
-
-</para>
-
-@parent:
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_prepend ##### -->
-<para>
-
-</para>
-
-@parent:
-@node:
-@Returns:
-
-
-<!-- ##### MACRO g_node_insert_data ##### -->
-<para>
-
-</para>
-
-@parent:
-@position:
-@data:
-@Returns:
-
-
-<!-- ##### MACRO g_node_insert_data_before ##### -->
-<para>
-
-</para>
-
-@parent:
-@sibling:
-@data:
-@Returns:
-
-
-<!-- ##### MACRO g_node_append_data ##### -->
-<para>
-
-</para>
-
-@parent:
-@data:
-@Returns:
-
-
-<!-- ##### MACRO g_node_prepend_data ##### -->
-<para>
-
-</para>
-
-@parent:
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_reverse_children ##### -->
-<para>
-
-</para>
-
-@node:
-
-
-<!-- ##### FUNCTION g_node_traverse ##### -->
-<para>
-
-</para>
-
-@root:
-@order:
-@flags:
-@max_depth:
-@func:
-@data:
-
-
-<!-- ##### ENUM GTraverseFlags ##### -->
-<para>
-Specifies which nodes are visited during several of the tree functions,
-including g_node_traverse() and g_node_find().
-</para>
-
-@G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has been
- introduced in 2.6, for older version use %G_TRAVERSE_LEAFS.
-@G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This name
- has been introduced in 2.6, for older version use %G_TRAVERSE_NON_LEAFS.
-@G_TRAVERSE_ALL: all nodes should be visited.
-@G_TRAVERSE_MASK: a mask of all traverse flags.
-@G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES.
-@G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES.
-
-<!-- ##### USER_FUNCTION GNodeTraverseFunc ##### -->
-<para>
-Specifies the type of function passed to g_node_traverse().
-The function is called with each of the nodes visited, together with the
-user data passed to g_node_traverse().
-If the function returns %TRUE, then the traversal is stopped.
-</para>
-
-@node: a #GNode.
-@data: user data passed to g_node_traverse().
-@Returns: %TRUE to stop the traversal.
-
-
-<!-- ##### FUNCTION g_node_children_foreach ##### -->
-<para>
-
-</para>
-
-@node:
-@flags:
-@func:
-@data:
-
-
-<!-- ##### USER_FUNCTION GNodeForeachFunc ##### -->
-<para>
-Specifies the type of function passed to g_node_children_foreach().
-The function is called with each child node, together with the user data
-passed to g_node_children_foreach().
-</para>
-
-@node: a #GNode.
-@data: user data passed to g_node_children_foreach().
-
-
-<!-- ##### FUNCTION g_node_get_root ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_find ##### -->
-<para>
-
-</para>
-
-@root:
-@order:
-@flags:
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_find_child ##### -->
-<para>
-
-</para>
-
-@node:
-@flags:
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_child_index ##### -->
-<para>
-
-</para>
-
-@node:
-@data:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_child_position ##### -->
-<para>
-
-</para>
-
-@node:
-@child:
-@Returns:
-
-
-<!-- ##### MACRO g_node_first_child ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_last_child ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_nth_child ##### -->
-<para>
-
-</para>
-
-@node:
-@n:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_first_sibling ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### MACRO g_node_next_sibling ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### MACRO g_node_prev_sibling ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_last_sibling ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### MACRO G_NODE_IS_LEAF ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### MACRO G_NODE_IS_ROOT ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_depth ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_n_nodes ##### -->
-<para>
-
-</para>
-
-@root:
-@flags:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_n_children ##### -->
-<para>
-
-</para>
-
-@node:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_is_ancestor ##### -->
-<para>
-
-</para>
-
-@node:
-@descendant:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_max_height ##### -->
-<para>
-
-</para>
-
-@root:
-@Returns:
-
-
-<!-- ##### FUNCTION g_node_unlink ##### -->
-<para>
-
-</para>
-
-@node:
-
-
-<!-- ##### FUNCTION g_node_destroy ##### -->
-<para>
-
-</para>
-
-@root:
-
-
-<!-- ##### FUNCTION g_node_push_allocator ##### -->
-<para>
-Sets the allocator to use to allocate #GNode elements.
-Use g_node_pop_allocator() to restore the previous allocator.
-</para>
-<para>
-Note that this function is not available if GLib has been compiled
-with <option>--disable-mem-pools</option>
-</para>
-
-@dummy: the #GAllocator to use when allocating #GNode elements.
-@Deprecated: 2.10: It does nothing, since #GNode has been converted
- to the <link linkend="glib-Memory-Slices">slice allocator</link>
-
-
-<!-- ##### FUNCTION g_node_pop_allocator ##### -->
-<para>
-Restores the previous #GAllocator, used when allocating #GNode elements.
-</para>
-<para>
-Note that this function is not available if GLib has been compiled
-with <option>--disable-mem-pools</option>
-</para>
-
-@Deprecated: 2.10: It does nothing, since #GNode has been converted
- to the <link linkend="glib-Memory-Slices">slice allocator</link>
-
-
#include "glib.h"
#include "galias.h"
+/**
+ * SECTION: trees-nary
+ * @title: N-ary Trees
+ * @short_description: trees of data with any number of branches
+ *
+ * The #GNode struct and its associated functions provide a N-ary tree
+ * data structure, where nodes in the tree can contain arbitrary data.
+ *
+ * To create a new tree use g_node_new().
+ *
+ * To insert a node into a tree use g_node_insert(),
+ * g_node_insert_before(), g_node_append() and g_node_prepend().
+ *
+ * To create a new node and insert it into a tree use
+ * g_node_insert_data(), g_node_insert_data_before(),
+ * g_node_append_data() and g_node_prepend_data().
+ *
+ * To reverse the children of a node use g_node_reverse_children().
+ *
+ * To find a node use g_node_get_root(), g_node_find(),
+ * g_node_find_child(), g_node_child_index(), g_node_child_position(),
+ * g_node_first_child(), g_node_last_child(), g_node_nth_child(),
+ * g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling()
+ * or g_node_last_sibling().
+ *
+ * To get information about a node or tree use G_NODE_IS_LEAF(),
+ * G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(),
+ * g_node_n_children(), g_node_is_ancestor() or g_node_max_height().
+ *
+ * To traverse a tree, calling a function for each node visited in the
+ * traversal, use g_node_traverse() or g_node_children_foreach().
+ *
+ * To remove a node or subtree from a tree use g_node_unlink() or
+ * g_node_destroy().
+ **/
+
+/**
+ * GNode:
+ * @data: contains the actual data of the node.
+ * @next: points to the node's next sibling (a sibling is another
+ * #GNode with the same parent).
+ * @prev: points to the node's previous sibling.
+ * @parent: points to the parent of the #GNode, or is %NULL if the
+ * #GNode is the root of the tree.
+ * @children: points to the first child of the #GNode. The other
+ * children are accessed by using the @next pointer of each
+ * child.
+ *
+ * The #GNode struct represents one node in a
+ * <link linkend="glib-N-ary-Trees">N-ary Tree</link>. fields
+ **/
+
+/**
+ * g_node_push_allocator:
+ * @dummy: the #GAllocator to use when allocating #GNode elements.
+ *
+ * Sets the allocator to use to allocate #GNode elements. Use
+ * g_node_pop_allocator() to restore the previous allocator.
+ *
+ * Note that this function is not available if GLib has been compiled
+ * with <option>--disable-mem-pools</option>
+ *
+ * Deprecated:2.10: It does nothing, since #GNode has been converted to
+ * the <link linkend="glib-Memory-Slices">slice
+ * allocator</link>
+ **/
void g_node_push_allocator (gpointer dummy) { /* present for binary compat only */ }
+
+/**
+ * g_node_pop_allocator:
+ *
+ * Restores the previous #GAllocator, used when allocating #GNode
+ * elements.
+ *
+ * Note that this function is not available if GLib has been compiled
+ * with <option>--disable-mem-pools</option>
+ *
+ * Deprecated:2.10: It does nothing, since #GNode has been converted to
+ * the <link linkend="glib-Memory-Slices">slice
+ * allocator</link>
+ **/
void g_node_pop_allocator (void) { /* present for binary compat only */ }
#define g_node_alloc0() g_slice_new0 (GNode)
* It calls the given function for each node visited.
* The traversal can be halted at any point by returning %TRUE from @func.
*/
+/**
+ * GTraverseFlags:
+ * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has
+ * been introduced in 2.6, for older version use
+ * %G_TRAVERSE_LEAFS.
+ * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This
+ * name has been introduced in 2.6, for older
+ * version use %G_TRAVERSE_NON_LEAFS.
+ * @G_TRAVERSE_ALL: all nodes should be visited.
+ * @G_TRAVERSE_MASK: a mask of all traverse flags.
+ * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES.
+ * @G_TRAVERSE_NON_LEAFS: identical to %G_TRAVERSE_NON_LEAVES.
+ *
+ * Specifies which nodes are visited during several of the tree
+ * functions, including g_node_traverse() and g_node_find().
+ **/
+/**
+ * GNodeTraverseFunc:
+ * @node: a #GNode.
+ * @data: user data passed to g_node_traverse().
+ * @Returns: %TRUE to stop the traversal.
+ *
+ * Specifies the type of function passed to g_node_traverse(). The
+ * function is called with each of the nodes visited, together with the
+ * user data passed to g_node_traverse(). If the function returns
+ * %TRUE, then the traversal is stopped.
+ **/
void
g_node_traverse (GNode *root,
GTraverseType order,
* Calls a function for each of the children of a #GNode.
* Note that it doesn't descend beneath the child nodes.
*/
+/**
+ * GNodeForeachFunc:
+ * @node: a #GNode.
+ * @data: user data passed to g_node_children_foreach().
+ *
+ * Specifies the type of function passed to g_node_children_foreach().
+ * The function is called with each child node, together with the user
+ * data passed to g_node_children_foreach().
+ **/
void
g_node_children_foreach (GNode *node,
GTraverseFlags flags,
#include "glib.h"
#include "galias.h"
+/**
+ * SECTION: trees-binary
+ * @title: Balanced Binary Trees
+ * @short_description: a sorted collection of key/value pairs optimized
+ * for searching and traversing in order
+ *
+ * The #GTree structure and its associated functions provide a sorted
+ * collection of key/value pairs optimized for searching and traversing
+ * in order.
+ *
+ * To create a new #GTree use g_tree_new().
+ *
+ * To insert a key/value pair into a #GTree use g_tree_insert().
+ *
+ * To lookup the value corresponding to a given key, use
+ * g_tree_lookup() and g_tree_lookup_extended().
+ *
+ * To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
+ * get the height of a #GTree, use g_tree_height().
+ *
+ * To traverse a #GTree, calling a function for each node visited in
+ * the traversal, use g_tree_foreach().
+ *
+ * To remove a key/value pair use g_tree_remove().
+ *
+ * To destroy a #GTree, use g_tree_destroy().
+ **/
+
#undef G_TREE_DEBUG
#define MAX_GTREE_HEIGHT 40
typedef struct _GTreeNode GTreeNode;
+/**
+ * GTree:
+ *
+ * The <structname>GTree</structname> struct is an opaque data
+ * structure representing a <link
+ * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It
+ * should be accessed only by using the following functions.
+ **/
struct _GTree
{
GTreeNode *root;
* instead. If you really need to visit nodes in a different order, consider
* using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
**/
+/**
+ * GTraverseFunc:
+ * @key: a key of a #GTree node.
+ * @value: the value corresponding to the key.
+ * @data: user data passed to g_tree_traverse().
+ * @Returns: %TRUE to stop the traversal.
+ *
+ * Specifies the type of function passed to g_tree_traverse(). It is
+ * passed the key and value of each node, together with the @user_data
+ * parameter passed to g_tree_traverse(). If the function returns
+ * %TRUE, the traversal is stopped.
+ **/
+/**
+ * GTraverseType:
+ * @G_IN_ORDER: vists a node's left child first, then the node itself,
+ * then its right child. This is the one to use if you
+ * want the output sorted according to the compare
+ * function.
+ * @G_PRE_ORDER: visits a node, then its children.
+ * @G_POST_ORDER: visits the node's children, then the node itself.
+ * @G_LEVEL_ORDER: is not implemented for <link
+ * linkend="glib-Balanced-Binary-Trees">Balanced Binary
+ * Trees</link>. For <link
+ * linkend="glib-N-ary-Trees">N-ary Trees</link>, it
+ * vists the root node first, then its children, then
+ * its grandchildren, and so on. Note that this is less
+ * efficient than the other orders.
+ *
+ * Specifies the type of traveral performed by g_tree_traverse(),
+ * g_node_traverse() and g_node_find().
+ **/
void
g_tree_traverse (GTree *tree,
GTraverseFunc traverse_func,
projects / platform / upstream / glib.git / commitdiff