Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:49:03 2009

## Asterisk developer's documentation

# linkedlists.h File Reference

A set of macros to manage forward-linked lists. More...

`#include "asterisk/lock.h"`

Include dependency graph for linkedlists.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Defines

#define | AST_LIST_APPEND_LIST(head, list, field)
| Appends a whole list to the tail of a list.
#define | AST_LIST_EMPTY(head) (AST_LIST_FIRST(head) == NULL)
| Checks whether the specified list contains any entries.
#define | AST_LIST_ENTRY(type)
| Declare a forward link structure inside a list entry.
#define | AST_LIST_FIRST(head) ((head)->first)
| Returns the first entry contained in a list.
#define | AST_LIST_HEAD(name, type)
| Defines a structure to be used to hold a list of specified type.
#define | AST_LIST_HEAD_DESTROY(head)
| Destroys a list head structure.
#define | AST_LIST_HEAD_INIT(head)
| Initializes a list head structure.
#define | AST_LIST_HEAD_INIT_NOLOCK(head)
| Initializes a list head structure.
#define | AST_LIST_HEAD_INIT_VALUE
| Defines initial values for a declaration of AST_LIST_HEAD.
#define | AST_LIST_HEAD_NOLOCK(name, type)
| Defines a structure to be used to hold a list of specified type (with no lock).
#define | AST_LIST_HEAD_NOLOCK_INIT_VALUE
| Defines initial values for a declaration of AST_LIST_HEAD_NOLOCK.
#define | AST_LIST_HEAD_NOLOCK_STATIC(name, type)
| Defines a structure to be used to hold a list of specified type, statically initialized.
#define | AST_LIST_HEAD_SET(head, entry)
| Initializes a list head structure with a specified first entry.
#define | AST_LIST_HEAD_SET_NOLOCK(head, entry)
| Initializes a list head structure with a specified first entry.
#define | AST_LIST_HEAD_STATIC(name, type)
| Defines a structure to be used to hold a list of specified type, statically initialized.
#define | AST_LIST_INSERT_AFTER(head, listelm, elm, field)
| Inserts a list entry after a given entry.
#define | AST_LIST_INSERT_HEAD(head, elm, field)
| Inserts a list entry at the head of a list.
#define | AST_LIST_INSERT_TAIL(head, elm, field)
| Appends a list entry to the tail of a list.
#define | AST_LIST_LAST(head) ((head)->last)
| Returns the last entry contained in a list.
#define | AST_LIST_LOCK(head) ast_mutex_lock(&(head)->lock)
| Attempts to lock a list.
#define | AST_LIST_NEXT(elm, field) ((elm)->field.next)
| Returns the next entry in the list after the given entry.
#define | AST_LIST_REMOVE(head, elm, field)
| Removes a specific entry from a list.
#define | AST_LIST_REMOVE_CURRENT(head, field)
| Removes the current entry from a list during a traversal.
#define | AST_LIST_REMOVE_HEAD(head, field)
| Removes and returns the head entry from a list.
#define | AST_LIST_TRAVERSE(head, var, field) for((var) = (head)->first; (var); (var) = (var)->field.next)
| Loops over (traverses) the entries in a list.
#define | AST_LIST_TRAVERSE_SAFE_BEGIN(head, var, field)
| Loops safely over (traverses) the entries in a list.
#define | AST_LIST_TRAVERSE_SAFE_END }
| Closes a safe loop traversal block.
#define | AST_LIST_UNLOCK(head) ast_mutex_unlock(&(head)->lock)
| Attempts to unlock a list.

## Detailed Description

A set of macros to manage forward-linked lists.

Definition in file linkedlists.h.

## Define Documentation

#define AST_LIST_APPEND_LIST | ( | head,
|  | list,
|  | field |  | ) |

Appends a whole list to the tail of a list.

Parameters:

  | head | This is a pointer to the list head structure
  | list | This is a pointer to the list to be appended.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Definition at line 439 of file linkedlists.h.

Referenced by clone_variables().

#define AST_LIST_EMPTY | ( | head |  | ) | (AST_LIST_FIRST(head) == NULL)

Checks whether the specified list contains any entries.

Parameters:

  | head | This is a pointer to the list head structure

Returns non-zero if the list has entries, zero if not.

Definition at line 230 of file linkedlists.h.

Referenced by app_exec(), ast_cdr_free_vars(), dundi_lookup_local(), get_destination(), handle_showfeatures(), loopback_helper(), register_verify(), reload_config(), sip_show_domains(), and sip_show_settings().

#define AST_LIST_ENTRY | ( | type |  | ) |

Value:

    struct {                      \
       struct type *next;                  \
    }

Declare a forward link structure inside a list entry.

Parameters:

  | type | This is the type of each list entry.

This macro declares a structure to be used to link list entries together. It must be used inside the definition of the structure named in type, as follows:

      struct list_entry {
       ...
       AST_LIST_ENTRY(list_entry) list;
      }

The field name list here is arbitrary, and can be anything you wish.

Definition at line 199 of file linkedlists.h.

#define AST_LIST_FIRST | ( | head |  | ) | ((head)->first)

Returns the first entry contained in a list.

Parameters:

  | head | This is a pointer to the list head structure

Definition at line 208 of file linkedlists.h.

Referenced by __ast_device_state_changed_literal(), ast_add_extension2(), ast_app_group_list_head(), clone_variables(), conf_cmd(), gen_readframe(), and spy_cleanup().

#define AST_LIST_HEAD | ( | name,
|  | type |  | ) |

Value:

    struct name {                       \
       struct type *first;                 \
       struct type *last;                  \
       ast_mutex_t lock;                \
    }

Defines a structure to be used to hold a list of specified type.

Parameters:

  | name | This will be the name of the defined structure.
  | type | This is the type of each list entry.

This macro creates a structure definition that can be used to hold a list of the entries of type type. It does not actually declare (allocate) a structure; to do that, either follow this macro with the desired name of the instance you wish to declare, or use the specified name to declare instances elsewhere.

Example usage:

      static AST_LIST_HEAD(entry_list, entry) entries;

This would define `struct` `entry_list`, and declare an instance of it named entries, all intended to hold a list of type `struct` `entry`.

Definition at line 71 of file linkedlists.h.

#define AST_LIST_HEAD_DESTROY | ( | head |  | ) |

Value:

    {              \
       (head)->first = NULL;                  \
       (head)->last = NULL;                \
       ast_mutex_destroy(&(head)->lock);            \
    }

Destroys a list head structure.

Parameters:

  | head | This is a pointer to the list head structure

This macro destroys a list head structure by setting the head entry to NULL (empty list) and destroying the embedded lock. It does not free the structure from memory.

Definition at line 362 of file linkedlists.h.

#define AST_LIST_HEAD_INIT | ( | head |  | ) |

Value:

    {              \
       (head)->first = NULL;                  \
       (head)->last = NULL;                \
       ast_mutex_init(&(head)->lock);               \
    }

Initializes a list head structure.

Parameters:

  | head | This is a pointer to the list head structure

This macro initializes a list head structure by setting the head entry to NULL (empty list) and recreating the embedded lock.

Definition at line 348 of file linkedlists.h.

Referenced by app_exec(), and ast_merge_contexts_and_delete().

#define AST_LIST_HEAD_INIT_NOLOCK | ( | head |  | ) |

Value:

    {           \
       (head)->first = NULL;                  \
       (head)->last = NULL;                \
    }

Initializes a list head structure.

Parameters:

  | head | This is a pointer to the list head structure

This macro initializes a list head structure by setting the head entry to NULL (empty list). There is no embedded lock handling with this macro.

Definition at line 376 of file linkedlists.h.

Referenced by ast_channel_alloc(), ast_channel_spy_add(), clone_variables(), dundi_lookup_local(), load_pbx(), and loopback_helper().

#define AST_LIST_HEAD_INIT_VALUE

Value:

    {     \
       .first = NULL,             \
       .last = NULL,              \
       .lock = AST_MUTEX_INIT_VALUE,       \
       }

Defines initial values for a declaration of AST_LIST_HEAD.

Definition at line 106 of file linkedlists.h.

#define AST_LIST_HEAD_NOLOCK | ( | name,
|  | type |  | ) |

Value:

    struct name {                       \
       struct type *first;                 \
       struct type *last;                  \
    }

Defines a structure to be used to hold a list of specified type (with no lock).

Parameters:

  | name | This will be the name of the defined structure.
  | type | This is the type of each list entry.

This macro creates a structure definition that can be used to hold a list of the entries of type type. It does not actually declare (allocate) a structure; to do that, either follow this macro with the desired name of the instance you wish to declare, or use the specified name to declare instances elsewhere.

Example usage:

      static AST_LIST_HEAD_NOLOCK(entry_list, entry) entries;

This would define `struct` `entry_list`, and declare an instance of it named entries, all intended to hold a list of type `struct` `entry`.

Definition at line 97 of file linkedlists.h.

#define AST_LIST_HEAD_NOLOCK_INIT_VALUE

Value:

    {  \
       .first = NULL,             \
       .last = NULL,              \
       }

Defines initial values for a declaration of AST_LIST_HEAD_NOLOCK.

Definition at line 115 of file linkedlists.h.

#define AST_LIST_HEAD_NOLOCK_STATIC | ( | name,
|  | type |  | ) |

Value:

    struct name {                       \
       struct type *first;                 \
       struct type *last;                  \
    } name = AST_LIST_HEAD_NOLOCK_INIT_VALUE

Defines a structure to be used to hold a list of specified type, statically initialized.

This is the same as AST_LIST_HEAD_STATIC, except without the lock included.

Definition at line 149 of file linkedlists.h.

#define AST_LIST_HEAD_SET | ( | head,
|  | entry |  | ) |

Value:

    do {           \
       (head)->first = (entry);               \
       (head)->last = (entry);                \
       ast_mutex_init(&(head)->lock);               \
    } while (0)

Initializes a list head structure with a specified first entry.

Parameters:

  | head | This is a pointer to the list head structure
  | entry | pointer to the list entry that will become the head of the list

This macro initializes a list head structure by setting the head entry to the supplied value and recreating the embedded lock.

Definition at line 163 of file linkedlists.h.

#define AST_LIST_HEAD_SET_NOLOCK | ( | head,
|  | entry |  | ) |

Value:

    do {        \
       (head)->first = (entry);               \
       (head)->last = (entry);                \
    } while (0)

Initializes a list head structure with a specified first entry.

Parameters:

  | head | This is a pointer to the list head structure
  | entry | pointer to the list entry that will become the head of the list

This macro initializes a list head structure by setting the head entry to the supplied value.

Definition at line 177 of file linkedlists.h.

#define AST_LIST_HEAD_STATIC | ( | name,
|  | type |  | ) |

Value:

    struct name {                       \
       struct type *first;                 \
       struct type *last;                  \
       ast_mutex_t lock;                \
    } name = AST_LIST_HEAD_INIT_VALUE

Defines a structure to be used to hold a list of specified type, statically initialized.

Parameters:

  | name | This will be the name of the defined structure.
  | type | This is the type of each list entry.

This macro creates a structure definition that can be used to hold a list of the entries of type type, and allocates an instance of it, initialized to be empty.

Example usage:

      static AST_LIST_HEAD_STATIC(entry_list, entry);

This would define `struct` `entry_list`, intended to hold a list of type `struct` `entry`.

Definition at line 137 of file linkedlists.h.

#define AST_LIST_INSERT_AFTER | ( | head,
|  | listelm,
|  | elm,
|  | field |  | ) |

Inserts a list entry after a given entry.

Parameters:

  | head | This is a pointer to the list head structure
  | listelm | This is a pointer to the entry after which the new entry should be inserted.
  | elm | This is a pointer to the entry to be inserted.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Definition at line 390 of file linkedlists.h.

#define AST_LIST_INSERT_HEAD | ( | head,
|  | elm,
|  | field |  | ) |

Inserts a list entry at the head of a list.

Parameters:

  | head | This is a pointer to the list head structure
  | elm | This is a pointer to the entry to be inserted.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Definition at line 404 of file linkedlists.h.

Referenced by __ao2_link(), add_identifier(), add_to_interfaces(), ast_cdr_copy_vars(), ast_cdr_register(), ast_cdr_setvar(), ast_channel_spy_add(), ast_devstate_add(), ast_dnsmgr_get(), ast_merge_contexts_and_delete(), ast_register_feature(), ast_register_file_version(), build_conf(), dundi_lookup_local(), loopback_helper(), pbx_builtin_pushvar_helper(), pbx_builtin_setvar_helper(), and register_translator().

#define AST_LIST_INSERT_TAIL | ( | head,
|  | elm,
|  | field |  | ) |

Appends a list entry to the tail of a list.

Parameters:

  | head | This is a pointer to the list head structure
  | elm | This is a pointer to the entry to be appended.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Note: The link field in the appended entry is not modified, so if it is actually the head of a list itself, the entire list will be appended temporarily (until the next AST_LIST_INSERT_TAIL is performed).

Definition at line 422 of file linkedlists.h.

Referenced by __ao2_link(), __ast_device_state_changed_literal(), add_sip_domain(), app_exec(), ast_app_group_set_channel(), ast_channel_inherit_variables(), ast_channel_spy_add(), clone_variables(), conf_run(), gen_readframe(), and local_call().

#define AST_LIST_LAST | ( | head |  | ) | ((head)->last)

Returns the last entry contained in a list.

Parameters:

  | head | This is a pointer to the list tail structure

Definition at line 214 of file linkedlists.h.

Referenced by admin_exec(), and conf_run().

#define AST_LIST_LOCK | ( | head |  | ) | ast_mutex_lock(&(head)->lock)

Attempts to lock a list.

Parameters:

  | head | This is a pointer to the list head structure

This macro attempts to place an exclusive lock in the list head structure pointed to by head. Returns 0 on success, non-zero on failure

Definition at line 38 of file linkedlists.h.

Referenced by __ast_device_state_changed_literal(), add_identifier(), add_sip_domain(), add_to_interfaces(), app_exec(), ast_app_group_discard(), ast_app_group_get_count(), ast_app_group_list_lock(), ast_app_group_match_get_count(), ast_app_group_set_channel(), ast_app_group_update(), ast_cdr_register(), ast_cdr_unregister(), ast_devstate_add(), ast_devstate_del(), ast_dnsmgr_get(), ast_dnsmgr_release(), ast_register_feature(), ast_register_file_version(), ast_unregister_feature(), ast_unregister_features(), ast_unregister_file_version(), build_conf(), changethread(), check_sip_domain(), clear_and_free_interfaces(), clear_sip_domains(), complete_confcmd(), complete_show_version_files(), conf_cmd(), conf_exec(), conf_free(), conf_play(), conf_run(), del_identifier(), dispose_conf(), do_devstate_changes(), do_state_change(), drop_translator(), feature_exec_app(), find_conf(), find_feature(), find_identifier(), gen_readframe(), handle_cli_status(), handle_show_version_files(), handle_showfeatures(), post_cdr(), refresh_list(), register_translator(), remove_from_interfaces(), sip_show_domains(), and unregister_translators().

#define AST_LIST_NEXT | ( | elm,
|  | field |  | ) | ((elm)->field.next)

Returns the next entry in the list after the given entry.

Parameters:

  | elm | This is a pointer to the current entry.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Definition at line 222 of file linkedlists.h.

Referenced by ao2_iterator_next(), group_function_read(), group_list_function_read(), and group_show_channels().

#define AST_LIST_REMOVE | ( | head,
|  | elm,
|  | field |  | ) |

Removes a specific entry from a list.

Parameters:

  | head | This is a pointer to the list head structure
  | elm | This is a pointer to the entry to be removed.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Warning:
  The removed entry is not freed nor modified in any way.

Definition at line 477 of file linkedlists.h.

Referenced by ast_channel_spy_remove(), ast_dnsmgr_release(), ast_unregister_feature(), conf_run(), del_identifier(), and pbx_builtin_setvar_helper().

#define AST_LIST_REMOVE_CURRENT | ( | head,
|  | field |  | ) |

Removes the current entry from a list during a traversal.

Parameters:

  | head | This is a pointer to the list head structure
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Note:
  This macro can only be used inside an AST_LIST_TRAVERSE_SAFE_BEGIN() block; it is used to unlink the current entry from the list without affecting the list traversal (and without having to re-traverse the list to modify the previous entry, if any).

Definition at line 327 of file linkedlists.h.

Referenced by ao2_callback(), ast_app_group_discard(), ast_app_group_set_channel(), ast_cdr_setvar(), ast_cdr_unregister(), ast_channel_spy_stop_by_type(), ast_devstate_del(), ast_unregister_file_version(), conf_free(), detach_spies(), drop_translator(), and remove_from_interfaces().

#define AST_LIST_REMOVE_HEAD | ( | head,
|  | field |  | ) |

Removes and returns the head entry from a list.

Parameters:

  | head | This is a pointer to the list head structure
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

Removes the head entry from the list, and returns a pointer to it. This macro is safe to call on an empty list.

Definition at line 458 of file linkedlists.h.

Referenced by app_exec(), ast_cdr_free_vars(), ast_channel_free(), ast_merge_contexts_and_delete(), ast_unregister_features(), clear_and_free_interfaces(), clear_sip_domains(), do_devstate_changes(), dundi_lookup_local(), gen_nextfile(), loopback_helper(), pbx_builtin_clear_globals(), and unregister_translators().

#define AST_LIST_TRAVERSE | ( | head,
|  | var,
|  | field |  | ) | for((var) = (head)->first; (var); (var) = (var)->field.next)

Loops over (traverses) the entries in a list.

Parameters:

  | head | This is a pointer to the list head structure
  | var | This is the name of the variable that will hold a pointer to the current list entry on each iteration. It must be declared before calling this macro.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

This macro is use to loop over (traverse) the entries in a list. It uses a for loop, and supplies the enclosed code with a pointer to each list entry as it loops. It is typically used as follows:

      static AST_LIST_HEAD(entry_list, list_entry) entries;
      ...
      struct list_entry {
       ...
       AST_LIST_ENTRY(list_entry) list;
      }
      ...
      struct list_entry *current;
      ...
      AST_LIST_TRAVERSE(&entries, current, list) {
         (do something with current here)
      }

Warning:
  If you modify the forward-link pointer contained in the current entry while inside the loop, the behavior will be unpredictable. At a minimum, the following macros will modify the forward-link pointer, and should not be used inside AST_LIST_TRAVERSE() against the entry pointed to by the current pointer without careful consideration of their consequences:
  - AST_LIST_NEXT() (when used as an lvalue)
  - AST_LIST_INSERT_AFTER()
  - AST_LIST_INSERT_HEAD()
  - AST_LIST_INSERT_TAIL()

Definition at line 268 of file linkedlists.h.

Referenced by add_identifier(), add_to_interfaces(), admin_exec(), ao2_iterator_next(), aPGSQL_fetch(), ast_app_group_get_count(), ast_app_group_match_get_count(), ast_app_group_update(), ast_cdr_copy_vars(), ast_cdr_getvar_internal(), ast_cdr_register(), ast_cdr_serialize_variables(), ast_channel_inherit_variables(), ast_do_masquerade(), build_conf(), changethread(), check_sip_domain(), clone_variables(), complete_confcmd(), complete_show_version_files(), conf_cmd(), conf_exec(), del_identifier(), do_state_change(), feature_exec_app(), find_conf(), find_feature(), find_identifier(), find_user(), handle_cli_status(), handle_show_version_files(), handle_showfeatures(), launch_page(), local_call(), mgcp_call(), pbx_builtin_getvar_helper(), pbx_builtin_serialize_variables(), pbx_builtin_setvar_helper(), pbx_retrieve_variable(), post_cdr(), queue_frame_to_spies(), refresh_list(), sip_call(), sip_show_domains(), and transmit_invite().

#define AST_LIST_TRAVERSE_SAFE_BEGIN | ( | head,
|  | var,
|  | field |  | ) |

Loops safely over (traverses) the entries in a list.

Parameters:

  | head | This is a pointer to the list head structure
  | var | This is the name of the variable that will hold a pointer to the current list entry on each iteration. It must be declared before calling this macro.
  | field | This is the name of the field (declared using AST_LIST_ENTRY()) used to link entries of this list together.

This macro is used to safely loop over (traverse) the entries in a list. It uses a for loop, and supplies the enclosed code with a pointer to each list entry as it loops. It is typically used as follows:

      static AST_LIST_HEAD(entry_list, list_entry) entries;
      ...
      struct list_entry {
       ...
       AST_LIST_ENTRY(list_entry) list;
      }
      ...
      struct list_entry *current;
      ...
      AST_LIST_TRAVERSE_SAFE_BEGIN(&entries, current, list) {
         (do something with current here)
      }
      AST_LIST_TRAVERSE_SAFE_END;

It differs from AST_LIST_TRAVERSE() in that the code inside the loop can modify (or even free, after calling AST_LIST_REMOVE_CURRENT()) the entry pointed to by the current pointer without affecting the loop traversal.

Definition at line 304 of file linkedlists.h.

Referenced by ao2_callback(), ast_app_group_discard(), ast_app_group_set_channel(), ast_cdr_setvar(), ast_cdr_unregister(), ast_channel_spy_stop_by_type(), ast_devstate_del(), ast_unregister_file_version(), conf_free(), detach_spies(), drop_translator(), and remove_from_interfaces().

#define AST_LIST_TRAVERSE_SAFE_END }

Closes a safe loop traversal block.

Definition at line 339 of file linkedlists.h.

Referenced by ao2_callback(), ast_app_group_discard(), ast_app_group_set_channel(), ast_cdr_setvar(), ast_cdr_unregister(), ast_channel_spy_stop_by_type(), ast_devstate_del(), ast_unregister_file_version(), conf_free(), detach_spies(), drop_translator(), and remove_from_interfaces().

#define AST_LIST_UNLOCK | ( | head |  | ) | ast_mutex_unlock(&(head)->lock)

Attempts to unlock a list.

Parameters:

  | head | This is a pointer to the list head structure

This macro attempts to remove an exclusive lock from the list head structure pointed to by head. If the list was not locked by this thread, this macro has no effect.

Definition at line 49 of file linkedlists.h.

Referenced by __ast_device_state_changed_literal(), add_identifier(), add_sip_domain(), add_to_interfaces(), app_exec(), ast_app_group_discard(), ast_app_group_get_count(), ast_app_group_list_unlock(), ast_app_group_match_get_count(), ast_app_group_set_channel(), ast_app_group_update(), ast_cdr_register(), ast_cdr_unregister(), ast_devstate_add(), ast_devstate_del(), ast_dnsmgr_get(), ast_dnsmgr_release(), ast_register_feature(), ast_register_file_version(), ast_unregister_feature(), ast_unregister_features(), ast_unregister_file_version(), build_conf(), changethread(), check_sip_domain(), clear_and_free_interfaces(), clear_sip_domains(), complete_confcmd(), complete_show_version_files(), conf_cmd(), conf_exec(), conf_free(), conf_play(), conf_run(), del_identifier(), dispose_conf(), do_devstate_changes(), do_state_change(), drop_translator(), feature_exec_app(), find_conf(), find_feature(), find_identifier(), gen_readframe(), handle_cli_status(), handle_show_version_files(), handle_showfeatures(), post_cdr(), refresh_list(), register_translator(), remove_from_interfaces(), sip_show_domains(), and unregister_translators().