Merge changes from team/russell/iax2_find_callno_1.2

These changes address a critical performance issue introduced in the latest
release.  The fix for the latest security issue included a change that made
Asterisk randomly choose call numbers to make them more difficult to guess by
attackers.  However, due to some inefficient (this is by far, an understatement)
code, when Asterisk chose high call numbers, chan_iax2 became unusable after
just a small number of calls.  On a small embedded platform, it would not be
able to handle a single call.  On my Intel Core 2 Duo @ 2.33 GHz, I couldn't
run more than about 16 IAX2 channels.  Ouch.

These changes address some performance issues of the find_callno() function
that have bothered me for a very long time.  On every incoming media frame,
it iterated through every possible call number trying to find a matching
active call.  This involved a mutex lock and unlock for each call number
checked.  So, if the random call number chosen was 20000, then every media
frame would cause 20000 locks and unlocks.  Previously, this problem was
not as obvious since Asterisk always chose the lowest call number it could.

A second container for IAX2 pvt structs has been added.  It is an astobj2
hash table.  When we know the remote side's call number, the pvt goes into
the hash table with a hash value of the remote side's call number.  Then,
lookups for incoming media frames are a very fast hash lookup instead of an
absolutely insane array traversal.

In a quick test, I was able to get more than 3600% more IAX2 channels
on my machine with these changes.


git-svn-id: http://svn.digium.com/svn/asterisk/branches/1.2@115296 f38db490-d61c-443f-a65b-d21fe96a405b

2 files changed, 1515 insertions, 0 deletions

diff --git a/include/asterisk/astobj2.h b/include/asterisk/astobj2.h
new file mode 100644
index 000000000..bcb8addda
--- /dev/null
+++ b/include/asterisk/astobj2.h
@@ -0,0 +1,541 @@
+/*
+ * astobj2 - replacement containers for asterisk data structures.
+ *
+ * Copyright (C) 2006 Marta Carbone, Luigi Rizzo - Univ. di Pisa, Italy
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _ASTERISK_ASTOBJ2_H
+#define _ASTERISK_ASTOBJ2_H
+
+/*! \file 
+ *
+ * \brief Object Model implementing objects and containers.
+
+These functions implement an abstraction for objects (with
+locks and reference counts) and containers for these user-defined objects,
+supporting locking, reference counting and callbacks.
+
+The internal implementation of the container is opaque to the user,
+so we can use different data structures as needs arise.
+
+At the moment, however, the only internal data structure is a hash
+table. When other structures will be implemented, the initialization
+function may change.
+
+USAGE - OBJECTS
+
+An object is a block of memory that must be allocated with the
+function ao2_alloc(), and for which the system keeps track (with
+abit of help from the programmer) of the number of references around.
+When an object has no more references, it is destroyed, by first
+invoking whatever 'destructor' function the programmer specifies
+(it can be NULL), and then freeing the memory.
+This way objects can be shared without worrying who is in charge
+of freeing them.
+
+Basically, creating an object requires the size of the object and
+and a pointer to the destructor function:
+ 
+    struct foo *o;
+ 
+    o = ao2_alloc(sizeof(struct foo), my_destructor_fn);
+
+The object returned has a refcount = 1.
+Note that the memory for the object is allocated and zeroed.
+- We cannot realloc() the object itself.
+- We cannot call free(o) to dispose of the object; rather we
+  tell the system that we do not need the reference anymore:
+
+    ao2_ref(o, -1)
+
+  causing the destructor to be called (and then memory freed) when
+  the refcount goes to 0. This is also available as ao2_unref(o),
+  and returns NULL as a convenience, so you can do things like
+	o = ao2_unref(o);
+  and clean the original pointer to prevent errors.
+
+- ao2_ref(o, +1) can be used to modify the refcount on the
+  object in case we want to pass it around.
+	
+
+- other calls on the object are ao2_lock(obj), ao2_unlock(),
+  ao2_trylock(), to manipulate the lock.
+
+
+USAGE - CONTAINERS
+
+A containers is an abstract data structure where we can store
+objects, search them (hopefully in an efficient way), and iterate
+or apply a callback function to them. A container is just an object
+itself.
+
+A container must first be allocated, specifying the initial
+parameters. At the moment, this is done as follows:
+
+    <b>Sample Usage:</b>
+    \code
+
+    struct ao2_container *c;
+
+    c = ao2_container_alloc(MAX_BUCKETS, my_hash_fn, my_cmp_fn);
+
+where
+- MAX_BUCKETS is the number of buckets in the hash table,
+- my_hash_fn() is the (user-supplied) function that returns a
+  hash key for the object (further reduced moduly MAX_BUCKETS
+  by the container's code);
+- my_cmp_fn() is the default comparison function used when doing
+  searches on the container,
+
+A container knows little or nothing about the object itself,
+other than the fact that it has been created by ao2_alloc()
+All knowledge of the (user-defined) internals of the object
+is left to the (user-supplied) functions passed as arguments
+to ao2_container_alloc().
+
+If we want to insert the object in the container, we should
+initialize its fields -- especially, those used by my_hash_fn() --
+to compute the bucket to use.
+Once done, we can link an object to a container with
+
+    ao2_link(c, o);
+
+The function returns NULL in case of errors (and the object
+is not inserted in the container). Other values mean success
+(we are not supposed to use the value as a pointer to anything).
+
+\note While an object o is in a container, we expect that
+my_hash_fn(o) will always return the same value. The function
+does not lock the object to be computed, so modifications of
+those fields that affect the computation of the hash should
+be done by extractiong the object from the container, and
+reinserting it after the change (this is not terribly expensive).
+
+\note A container with a single buckets is effectively a linked
+list. However there is no ordering among elements.
+
+Objects implement a reference counter keeping the count
+of the number of references that reference an object.
+
+When this number becomes zero the destructor will be
+called and the object will be free'd.
+ */
+
+/*!
+ * Invoked just before freeing the memory for the object.
+ * It is passed a pointer to user data.
+ */
+typedef void (*ao2_destructor_fn)(void *);
+
+void ao2_bt(void);	/* backtrace */
+/*!
+ * Allocate and initialize an object.
+ * 
+ * \param data_size The sizeof() of user-defined structure.
+ * \param destructor_fn The function destructor (can be NULL)
+ * \return A pointer to user data. 
+ *
+ * Allocates a struct astobj2 with sufficient space for the
+ * user-defined structure.
+ * \notes:
+ * - storage is zeroed; XXX maybe we want a flag to enable/disable this.
+ * - the refcount of the object just created is 1
+ * - the returned pointer cannot be free()'d or realloc()'ed;
+ *   rather, we just call ao2_ref(o, -1);
+ */
+void *ao2_alloc(const size_t data_size, ao2_destructor_fn destructor_fn);
+
+/*!
+ * Reference/unreference an object and return the old refcount.
+ *
+ * \param o A pointer to the object
+ * \param delta Value to add to the reference counter.
+ * \return The value of the reference counter before the operation.
+ *
+ * Increase/decrease the reference counter according
+ * the value of delta.
+ *
+ * If the refcount goes to zero, the object is destroyed.
+ *
+ * \note The object must not be locked by the caller of this function, as
+ *       it is invalid to try to unlock it after releasing the reference.
+ *
+ * \note if we know the pointer to an object, it is because we
+ * have a reference count to it, so the only case when the object
+ * can go away is when we release our reference, and it is
+ * the last one in existence.
+ */
+int ao2_ref(void *o, int delta);
+
+/*!
+ * Lock an object.
+ * 
+ * \param a A pointer to the object we want lock.
+ * \return 0 on success, other values on error.
+ */
+int ao2_lock(void *a);
+
+/*!
+ * Unlock an object.
+ * 
+ * \param a A pointer to the object we want unlock.
+ * \return 0 on success, other values on error.
+ */
+int ao2_unlock(void *a);
+
+/*!
+ *
+ * Containers
+
+containers are data structures meant to store several objects,
+and perform various operations on them.
+Internally, objects are stored in lists, hash tables or other
+data structures depending on the needs.
+
+NOTA BENE: at the moment the only container we support is the
+hash table and its degenerate form, the list.
+
+Operations on container include:
+
+    c = ao2_container_alloc(size, cmp_fn, hash_fn)
+	allocate a container with desired size and default compare
+	and hash function
+
+    ao2_find(c, arg, flags)
+	returns zero or more element matching a given criteria
+	(specified as arg). Flags indicate how many results we
+	want (only one or all matching entries), and whether we
+	should unlink the object from the container.
+
+    ao2_callback(c, flags, fn, arg)
+	apply fn(obj, arg) to all objects in the container.
+	Similar to find. fn() can tell when to stop, and
+	do anything with the object including unlinking it.
+	Note that the entire operation is run with the container
+	locked, so noone else can change its content while we work on it.
+	However, we pay this with the fact that doing
+	anything blocking in the callback keeps the container
+	blocked.
+	The mechanism is very flexible because the callback function fn()
+	can do basically anything e.g. counting, deleting records, etc.
+	possibly using arg to store the results.
+   
+    iterate on a container
+	this is done with the following sequence
+
+	    struct ao2_container *c = ... // our container
+	    struct ao2_iterator i;
+	    void *o;
+
+	    i = ao2_iterator_init(c, flags);
+     
+	    while ( (o = ao2_iterator_next(&i)) ) {
+		... do something on o ...
+		ao2_ref(o, -1);
+	    }
+
+	The difference with the callback is that the control
+	on how to iterate is left to us.
+
+    ao2_ref(c, -1)
+	dropping a reference to a container destroys it, very simple!
+ 
+Containers are astobj2 object themselves, and this is why their
+implementation is simple too.
+
+ */
+
+/*!
+ * We can perform different operation on an object. We do this
+ * according the following flags.
+ */
+enum search_flags {
+	/*! unlink the object found */
+	OBJ_UNLINK	 = (1 << 0),
+	/*! on match, don't return the object or increase its reference count. */
+	OBJ_NODATA	 = (1 << 1),
+	/*! don't stop at the first match 
+	 *  \note This is not fully implemented. */
+	OBJ_MULTIPLE = (1 << 2),
+	/*! obj is an object of the same type as the one being searched for.
+	 *  This implies that it can be passed to the object's hash function
+	 *  for optimized searching. */
+	OBJ_POINTER	 = (1 << 3),
+};
+
+/*!
+ * Type of a generic function to generate a hash value from an object.
+ *
+ */
+typedef int (*ao2_hash_fn)(const void *obj, const int flags);
+
+/*!
+ * valid callback results:
+ * We return a combination of
+ * CMP_MATCH when the object matches the request,
+ * and CMP_STOP when we should not continue the search further.
+ */
+enum _cb_results {
+	CMP_MATCH	= 0x1,
+	CMP_STOP	= 0x2,
+};
+
+/*!
+ * generic function to compare objects.
+ * This, as other callbacks, should return a combination of
+ * _cb_results as described above.
+ *
+ * \param o	object from container
+ * \param arg	search parameters (directly from ao2_find)
+ * \param flags	passed directly from ao2_find
+ *	XXX explain.
+ */
+
+/*!
+ * Type of a generic callback function
+ * \param obj  pointer to the (user-defined part) of an object.
+ * \param arg callback argument from ao2_callback()
+ * \param flags flags from ao2_callback()
+ * The return values are the same as a compare function.
+ * In fact, they are the same thing.
+ */
+typedef int (*ao2_callback_fn)(void *obj, void *arg, int flags);
+
+/*!
+ * Here start declarations of containers.
+ */
+struct ao2_container;
+
+/*!
+ * Allocate and initialize a container 
+ * with the desired number of buckets.
+ * 
+ * We allocate space for a struct astobj_container, struct container
+ * and the buckets[] array.
+ *
+ * \param my_hash_fn Pointer to a function computing a hash value.
+ * \param my_cmp_fn Pointer to a function comparating key-value 
+ * 			with a string. (can be NULL)
+ * \return A pointer to a struct container.
+ *
+ * destructor is set implicitly.
+ */
+struct ao2_container *ao2_container_alloc(const uint n_buckets,
+		ao2_hash_fn hash_fn, ao2_callback_fn cmp_fn);
+
+/*!
+ * Returns the number of elements in a container.
+ */
+int ao2_container_count(struct ao2_container *c);
+
+/*
+ * Here we have functions to manage objects.
+ *
+ * We can use the functions below on any kind of 
+ * object defined by the user.
+ */
+
+/*!
+ * \brief Add an object to a container.
+ *
+ * \param c the container to operate on.
+ * \param newobj the object to be added.
+ *
+ * \return NULL on errors, other values on success.
+ *
+ * This function inserts an object in a container according its key.
+ *
+ * \note Remember to set the key before calling this function.
+ *
+ * \note This function automatically increases the reference count to
+ *       account for the reference to the object that the container now holds.
+ *
+ * For Asterisk 1.4 only, there is a dirty hack here to ensure that chan_iax2
+ * can have objects linked in to the container at the head instead of tail
+ * when it is just a linked list.  This is to maintain some existing behavior
+ * where the order must be maintained as it was before this conversion so that
+ * matching behavior doesn't change.
+ */
+#define ao2_link(c, o) __ao2_link(c, o, 0)
+void *__ao2_link(struct ao2_container *c, void *newobj, int iax2_hack);
+
+/*!
+ * \brief Remove an object from the container
+ *
+ * \arg c the container
+ * \arg obj the object to unlink
+ *
+ * \retval NULL, always
+ *
+ * \note The object requested to be unlinked must be valid.  However, if it turns
+ *       out that it is not in the container, this function is still safe to
+ *       be called.
+ *
+ * \note If the object gets unlinked from the container, the container's
+ *       reference to the object will be automatically released.
+ */
+void *ao2_unlink(struct ao2_container *c, void *obj);
+
+/*! \struct Used as return value if the flag OBJ_MULTIPLE is set */
+struct ao2_list {
+	struct ao2_list *next;
+	void *obj;	/* pointer to the user portion of the object */
+};
+
+/*!
+ * ao2_callback() and astob2_find() are the same thing with only one difference:
+ * the latter uses as a callback the function passed as my_cmp_f() at
+ * the time of the creation of the container.
+ * 
+ * \param c A pointer to the container to operate on.
+ * \param arg passed to the callback.
+ * \param flags A set of flags specifying the operation to perform,
+	partially used by the container code, but also passed to
+	the callback.
+ * \return 	A pointer to the object found/marked, 
+ * 		a pointer to a list of objects matching comparison function,
+ * 		NULL if not found.
+ * If the function returns any objects, their refcount is incremented,
+ * and the caller is in charge of decrementing them once done.
+ * Also, in case of multiple values returned, the list used
+ * to store the objects must be freed by the caller.
+ *
+ * This function searches through a container and performs operations
+ * on objects according on flags passed.
+ * XXX describe better
+ * The comparison is done calling the compare function set implicitly. 
+ * The p pointer can be a pointer to an object or to a key, 
+ * we can say this looking at flags value.
+ * If p points to an object we will search for the object pointed
+ * by this value, otherwise we serch for a key value.
+ * If the key is not uniq we only find the first matching valued.
+ * If we use the OBJ_MARK flags, we mark all the objects matching 
+ * the condition.
+ *
+ * The use of flags argument is the follow:
+ *
+ *	OBJ_UNLINK 		unlinks the object found
+ *	OBJ_NODATA		on match, do return an object
+ *				Callbacks use OBJ_NODATA as a default
+ *				functions such as find() do
+ *	OBJ_MULTIPLE		return multiple matches
+ *				Default for _find() is no.
+ *				to a key (not yet supported)
+ *	OBJ_POINTER 		the pointer is an object pointer
+ *
+ * In case we return a list, the callee must take care to destroy 
+ * that list when no longer used.
+ *
+ * \note When the returned object is no longer in use, ao2_ref() should
+ * be used to free the additional reference possibly created by this function.
+ */
+/* XXX order of arguments to find */
+void *ao2_find(struct ao2_container *c, void *arg, enum search_flags flags);
+void *ao2_callback(struct ao2_container *c,
+	enum search_flags flags,
+	ao2_callback_fn cb_fn, void *arg);
+
+int ao2_match_by_addr(void *user_data, void *arg, int flags);
+/*!
+ *
+ *
+ * When we need to walk through a container, we use
+ * ao2_iterator to keep track of the current position.
+ * 
+ * Because the navigation is typically done without holding the
+ * lock on the container across the loop,
+ * objects can be inserted or deleted or moved
+ * while we work. As a consequence, there is no guarantee that
+ * the we manage to touch all the elements on the list, or it
+ * is possible that we touch the same object multiple times.
+ * However, within the current hash table container, the following is true:
+ *  - It is not possible to miss an object in the container while iterating
+ *    unless it gets added after the iteration begins and is added to a bucket
+ *    that is before the one the current object is in.  In this case, even if
+ *    you locked the container around the entire iteration loop, you still would
+ *    not see this object, because it would still be waiting on the container
+ *    lock so that it can be added.
+ *  - It would be extremely rare to see an object twice.  The only way this can
+ *    happen is if an object got unlinked from the container and added again 
+ *    during the same iteration.  Furthermore, when the object gets added back,
+ *    it has to be in the current or later bucket for it to be seen again.
+ *
+ * An iterator must be first initialized with ao2_iterator_init(),
+ * then we can use o = ao2_iterator_next() to move from one
+ * element to the next. Remember that the object returned by
+ * ao2_iterator_next() has its refcount incremented,
+ * and the reference must be explicitly released when done with it.
+ *
+ * Example:
+ *
+ *  \code
+ *
+ *  struct ao2_container *c = ... // the container we want to iterate on
+ *  struct ao2_iterator i;
+ *  struct my_obj *o;
+ *
+ *  i = ao2_iterator_init(c, flags);
+ *
+ *  while ( (o = ao2_iterator_next(&i)) ) {
+ *     ... do something on o ...
+ *     ao2_ref(o, -1);
+ *  }
+ *
+ *  \endcode
+ *
+ */
+
+/*!
+ * You are not supposed to know the internals of an iterator!
+ * We would like the iterator to be opaque, unfortunately
+ * its size needs to be known if we want to store it around
+ * without too much trouble.
+ * Anyways...
+ * The iterator has a pointer to the container, and a flags
+ * field specifying various things e.g. whether the container
+ * should be locked or not while navigating on it.
+ * The iterator "points" to the current object, which is identified
+ * by three values:
+ * - a bucket number;
+ * - the object_id, which is also the container version number
+ *   when the object was inserted. This identifies the object
+ *   univoquely, however reaching the desired object requires
+ *   scanning a list.
+ * - a pointer, and a container version when we saved the pointer.
+ *   If the container has not changed its version number, then we
+ *   can safely follow the pointer to reach the object in constant time.
+ * Details are in the implementation of ao2_iterator_next()
+ * A freshly-initialized iterator has bucket=0, version = 0.
+ */
+
+struct ao2_iterator {
+	/*! the container */
+	struct ao2_container *c;
+	/*! operation flags */
+	int flags;
+#define	F_AO2I_DONTLOCK	1	/*!< don't lock when iterating */
+	/*! current bucket */
+	int bucket;
+	/*! container version */
+	uint c_version;
+	/*! pointer to the current object */
+	void *obj;
+	/*! container version when the object was created */
+	uint version;
+};
+
+struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags);
+
+void *ao2_iterator_next(struct ao2_iterator *a);
+
+#endif /* _ASTERISK_ASTOBJ2_H */
diff --git a/include/asterisk/dlinkedlists.h b/include/asterisk/dlinkedlists.h
new file mode 100644
index 000000000..2f42fdd39
--- /dev/null
+++ b/include/asterisk/dlinkedlists.h
@@ -0,0 +1,974 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2007, Digium, Inc.
+ *
+ * Steve Murphy <murf@digium.com>
+ * 
+ * Doubly-Linked List Macros--
+ * Based on linkedlists.h (to the point of plagiarism!), which is by:
+ *
+ * Mark Spencer <markster@digium.com>
+ * Kevin P. Fleming <kpfleming@digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef ASTERISK_DLINKEDLISTS_H
+#define ASTERISK_DLINKEDLISTS_H
+
+#include "asterisk/lock.h"
+
+/*!
+  \file dlinkedlists.h
+  \brief A set of macros to manage doubly-linked lists.
+*/
+
+/*!
+  \brief Locks a list.
+  \param 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.
+  \retval 0 on success
+  \retval non-zero on failure
+*/
+#define AST_DLLIST_LOCK(head)						\
+	ast_mutex_lock(&(head)->lock) 
+
+/*!
+  \brief Write locks a list.
+  \param head This is a pointer to the list head structure
+
+  This macro attempts to place an exclusive write lock in the
+  list head structure pointed to by head.
+  \retval 0 on success
+  \retval non-zero on failure
+*/
+#define AST_RWDLLIST_WRLOCK(head)                                         \
+        ast_rwlock_wrlock(&(head)->lock)
+
+/*!
+  \brief Read locks a list.
+  \param head This is a pointer to the list head structure
+
+  This macro attempts to place a read lock in the
+  list head structure pointed to by head.
+  \retval 0 on success
+  \retval non-zero on failure
+*/
+#define AST_RWDLLIST_RDLOCK(head)                                         \
+        ast_rwlock_rdlock(&(head)->lock)
+	
+/*!
+  \brief Locks a list, without blocking if the list is locked.
+  \param 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.
+  \retval 0 on success
+  \retval non-zero on failure
+*/
+#define AST_DLLIST_TRYLOCK(head)						\
+	ast_mutex_trylock(&(head)->lock) 
+
+/*!
+  \brief Write locks a list, without blocking if the list is locked.
+  \param head This is a pointer to the list head structure
+
+  This macro attempts to place an exclusive write lock in the
+  list head structure pointed to by head.
+  \retval 0 on success
+  \retval non-zero on failure
+*/
+#define AST_RWDLLIST_TRYWRLOCK(head)                                      \
+        ast_rwlock_trywrlock(&(head)->lock)
+
+/*!
+  \brief Read locks a list, without blocking if the list is locked.
+  \param head This is a pointer to the list head structure
+
+  This macro attempts to place a read lock in the
+  list head structure pointed to by head.
+  \retval 0 on success
+  \retval non-zero on failure
+*/
+#define AST_RWDLLIST_TRYRDLOCK(head)                                      \
+        ast_rwlock_tryrdlock(&(head)->lock)
+	
+/*!
+  \brief Attempts to unlock a list.
+  \param 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.
+*/
+#define AST_DLLIST_UNLOCK(head) 						\
+	ast_mutex_unlock(&(head)->lock)
+
+/*!
+  \brief Attempts to unlock a read/write based list.
+  \param head This is a pointer to the list head structure
+
+  This macro attempts to remove a read or write lock from the
+  list head structure pointed to by head. If the list
+  was not locked by this thread, this macro has no effect.
+*/
+#define AST_RWDLLIST_UNLOCK(head)                                         \
+        ast_rwlock_unlock(&(head)->lock)
+
+/*!
+  \brief Defines a structure to be used to hold a list of specified type.
+  \param name This will be the name of the defined structure.
+  \param 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 \a 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 \a name to declare instances elsewhere.
+
+  Example usage:
+  \code
+  static AST_DLLIST_HEAD(entry_list, entry) entries;
+  \endcode
+
+  This would define \c struct \c entry_list, and declare an instance of it named
+  \a entries, all intended to hold a list of type \c struct \c entry.
+*/
+#define AST_DLLIST_HEAD(name, type)					\
+struct name {								\
+	struct type *first;						\
+	struct type *last;						\
+	ast_mutex_t lock;						\
+}
+
+/*!
+  \brief Defines a structure to be used to hold a read/write list of specified type.
+  \param name This will be the name of the defined structure.
+  \param 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 \a 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 \a name to declare instances elsewhere.
+
+  Example usage:
+  \code
+  static AST_RWDLLIST_HEAD(entry_list, entry) entries;
+  \endcode
+
+  This would define \c struct \c entry_list, and declare an instance of it named
+  \a entries, all intended to hold a list of type \c struct \c entry.
+*/
+#define AST_RWDLLIST_HEAD(name, type)                                     \
+struct name {                                                           \
+        struct type *first;                                             \
+        struct type *last;                                              \
+        ast_rwlock_t lock;                                              \
+}
+
+/*!
+  \brief Defines a structure to be used to hold a list of specified type (with no lock).
+  \param name This will be the name of the defined structure.
+  \param 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 \a 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 \a name to declare instances elsewhere.
+
+  Example usage:
+  \code
+  static AST_DLLIST_HEAD_NOLOCK(entry_list, entry) entries;
+  \endcode
+
+  This would define \c struct \c entry_list, and declare an instance of it named
+  \a entries, all intended to hold a list of type \c struct \c entry.
+*/
+#define AST_DLLIST_HEAD_NOLOCK(name, type)				\
+struct name {								\
+	struct type *first;						\
+	struct type *last;						\
+}
+
+/*!
+  \brief Defines initial values for a declaration of AST_DLLIST_HEAD
+*/
+#define AST_DLLIST_HEAD_INIT_VALUE	{		\
+	.first = NULL,					\
+	.last = NULL,					\
+	.lock = AST_MUTEX_INIT_VALUE,			\
+	}
+
+/*!
+  \brief Defines initial values for a declaration of AST_RWDLLIST_HEAD
+*/
+#define AST_RWDLLIST_HEAD_INIT_VALUE      {               \
+        .first = NULL,                                  \
+        .last = NULL,                                   \
+        .lock = AST_RWLOCK_INIT_VALUE,                  \
+        }
+
+/*!
+  \brief Defines initial values for a declaration of AST_DLLIST_HEAD_NOLOCK
+*/
+#define AST_DLLIST_HEAD_NOLOCK_INIT_VALUE	{	\
+	.first = NULL,					\
+	.last = NULL,					\
+	}
+
+/*!
+  \brief Defines a structure to be used to hold a list of specified type, statically initialized.
+  \param name This will be the name of the defined structure.
+  \param 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 \a type, and allocates an instance
+  of it, initialized to be empty.
+
+  Example usage:
+  \code
+  static AST_DLLIST_HEAD_STATIC(entry_list, entry);
+  \endcode
+
+  This would define \c struct \c entry_list, intended to hold a list of
+  type \c struct \c entry.
+*/
+#if defined(AST_MUTEX_INIT_W_CONSTRUCTORS)
+#define AST_DLLIST_HEAD_STATIC(name, type)				\
+struct name {								\
+	struct type *first;						\
+	struct type *last;						\
+	ast_mutex_t lock;						\
+} name;									\
+static void  __attribute__ ((constructor)) __init_##name(void)		\
+{									\
+        AST_DLLIST_HEAD_INIT(&name);					\
+}									\
+static void  __attribute__ ((destructor)) __fini_##name(void)		\
+{									\
+        AST_DLLIST_HEAD_DESTROY(&name);					\
+}									\
+struct __dummy_##name
+#else
+#define AST_DLLIST_HEAD_STATIC(name, type)				\
+struct name {								\
+	struct type *first;						\
+	struct type *last;						\
+	ast_mutex_t lock;						\
+} name = AST_DLLIST_HEAD_INIT_VALUE
+#endif
+
+/*!
+  \brief Defines a structure to be used to hold a read/write list of specified type, statically initialized.
+  \param name This will be the name of the defined structure.
+  \param 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 \a type, and allocates an instance
+  of it, initialized to be empty.
+
+  Example usage:
+  \code
+  static AST_RWDLLIST_HEAD_STATIC(entry_list, entry);
+  \endcode
+
+  This would define \c struct \c entry_list, intended to hold a list of
+  type \c struct \c entry.
+*/
+#ifndef AST_RWLOCK_INIT_VALUE
+#define AST_RWDLLIST_HEAD_STATIC(name, type)                              \
+struct name {                                                           \
+        struct type *first;                                             \
+        struct type *last;                                              \
+        ast_rwlock_t lock;                                              \
+} name;                                                                 \
+static void  __attribute__ ((constructor)) __init_##name(void)          \
+{                                                                       \
+        AST_RWDLLIST_HEAD_INIT(&name);                                    \
+}                                                                       \
+static void  __attribute__ ((destructor)) __fini_##name(void)           \
+{                                                                       \
+        AST_RWDLLIST_HEAD_DESTROY(&name);                                 \
+}                                                                       \
+struct __dummy_##name
+#else
+#define AST_RWDLLIST_HEAD_STATIC(name, type)                              \
+struct name {                                                           \
+        struct type *first;                                             \
+        struct type *last;                                              \
+        ast_rwlock_t lock;                                              \
+} name = AST_RWDLLIST_HEAD_INIT_VALUE
+#endif
+
+/*!
+  \brief Defines a structure to be used to hold a list of specified type, statically initialized.
+
+  This is the same as AST_DLLIST_HEAD_STATIC, except without the lock included.
+*/
+#define AST_DLLIST_HEAD_NOLOCK_STATIC(name, type)				\
+struct name {								\
+	struct type *first;						\
+	struct type *last;						\
+} name = AST_DLLIST_HEAD_NOLOCK_INIT_VALUE
+
+/*!
+  \brief Initializes a list head structure with a specified first entry.
+  \param head This is a pointer to the list head structure
+  \param 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.
+*/
+#define AST_DLLIST_HEAD_SET(head, entry) do {				\
+	(head)->first = (entry);					\
+	(head)->last = (entry);						\
+	ast_mutex_init(&(head)->lock);					\
+} while (0)
+
+/*!
+  \brief Initializes an rwlist head structure with a specified first entry.
+  \param head This is a pointer to the list head structure
+  \param 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.
+*/
+#define AST_RWDLLIST_HEAD_SET(head, entry) do {                           \
+        (head)->first = (entry);                                        \
+        (head)->last = (entry);                                         \
+        ast_rwlock_init(&(head)->lock);                                 \
+} while (0)
+
+/*!
+  \brief Initializes a list head structure with a specified first entry.
+  \param head This is a pointer to the list head structure
+  \param 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.
+*/
+#define AST_DLLIST_HEAD_SET_NOLOCK(head, entry) do {			\
+	(head)->first = (entry);					\
+	(head)->last = (entry);						\
+} while (0)
+
+/*!
+  \brief Declare previous/forward links inside a list entry.
+  \param type This is the type of each list entry.
+
+  This macro declares a structure to be used to doubly link list entries together.
+  It must be used inside the definition of the structure named in
+  \a type, as follows:
+
+  \code
+  struct list_entry {
+  	...
+  	AST_DLLIST_ENTRY(list_entry) list;
+  }
+  \endcode
+
+  The field name \a list here is arbitrary, and can be anything you wish.
+*/
+#define AST_DLLIST_ENTRY(type)			\
+struct {								\
+	struct type *prev;						\
+	struct type *next;						\
+}
+
+#define AST_RWDLLIST_ENTRY AST_DLLIST_ENTRY
+ 
+/*!
+  \brief Returns the first entry contained in a list.
+  \param head This is a pointer to the list head structure
+ */
+#define	AST_DLLIST_FIRST(head)	((head)->first)
+
+#define AST_RWDLLIST_FIRST AST_DLLIST_FIRST
+
+/*!
+  \brief Returns the last entry contained in a list.
+  \param head This is a pointer to the list head structure
+ */
+#define	AST_DLLIST_LAST(head)	((head)->last)
+
+#define AST_RWDLLIST_LAST AST_DLLIST_LAST
+
+/*!
+  \brief Returns the next entry in the list after the given entry.
+  \param elm This is a pointer to the current entry.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+*/
+#define AST_DLLIST_NEXT(elm, field)	((elm)->field.next)
+
+#define AST_RWDLLIST_NEXT AST_DLLIST_NEXT
+
+/*!
+  \brief Returns the previous entry in the list before the given entry.
+  \param elm This is a pointer to the current entry.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+*/
+#define AST_DLLIST_PREV(elm, field)	((elm)->field.prev)
+
+#define AST_RWDLLIST_PREV AST_DLLIST_PREV
+
+/*!
+  \brief Checks whether the specified list contains any entries.
+  \param head This is a pointer to the list head structure
+
+  \return non-zero if the list has entries
+  \return zero if not.
+ */
+#define	AST_DLLIST_EMPTY(head)	(AST_DLLIST_FIRST(head) == NULL)
+
+#define AST_RWDLLIST_EMPTY AST_DLLIST_EMPTY
+
+/*!
+  \brief Loops over (traverses) the entries in a list.
+  \param head This is a pointer to the list head structure
+  \param 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.
+  \param field This is the name of the field (declared using AST_DLLIST_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
+  \a for loop, and supplies the enclosed code with a pointer to each list
+  entry as it loops. It is typically used as follows:
+  \code
+  static AST_DLLIST_HEAD(entry_list, list_entry) entries;
+  ...
+  struct list_entry {
+  	...
+  	AST_DLLIST_ENTRY(list_entry) list;
+  }
+  ...
+  struct list_entry *current;
+  ...
+  AST_DLLIST_TRAVERSE(&entries, current, list) {
+     (do something with current here)
+  }
+  \endcode
+  \warning If you modify the forward-link pointer contained in the \a 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_DLLIST_TRAVERSE() against the entry pointed to by the \a current pointer without
+  careful consideration of their consequences:
+  \li AST_DLLIST_NEXT() (when used as an lvalue)
+  \li AST_DLLIST_INSERT_AFTER()
+  \li AST_DLLIST_INSERT_HEAD()
+  \li AST_DLLIST_INSERT_TAIL()
+*/
+#define AST_DLLIST_TRAVERSE(head,var,field) 				\
+	for((var) = (head)->first; (var); (var) = (var)->field.next)
+
+#define AST_RWDLLIST_TRAVERSE AST_DLLIST_TRAVERSE
+
+/*!
+  \brief Loops over (traverses) the entries in a list in reverse order, starting at the end.
+  \param head This is a pointer to the list head structure
+  \param 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.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+
+  This macro is use to loop over (traverse) the entries in a list in reverse order. It uses a
+  \a for loop, and supplies the enclosed code with a pointer to each list
+  entry as it loops. It is typically used as follows:
+  \code
+  static AST_DLLIST_HEAD(entry_list, list_entry) entries;
+  ...
+  struct list_entry {
+  	...
+  	AST_DLLIST_ENTRY(list_entry) list;
+  }
+  ...
+  struct list_entry *current;
+  ...
+  AST_DLLIST_TRAVERSE_BACKWARDS(&entries, current, list) {
+     (do something with current here)
+  }
+  \endcode
+  \warning If you modify the forward-link pointer contained in the \a 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_DLLIST_TRAVERSE() against the entry pointed to by the \a current pointer without
+  careful consideration of their consequences:
+  \li AST_DLLIST_PREV() (when used as an lvalue)
+  \li AST_DLLIST_INSERT_BEFORE()
+  \li AST_DLLIST_INSERT_HEAD()
+  \li AST_DLLIST_INSERT_TAIL()
+*/
+#define AST_DLLIST_TRAVERSE_BACKWARDS(head,var,field) 				\
+	for((var) = (head)->last; (var); (var) = (var)->field.prev)
+
+#define AST_RWDLLIST_TRAVERSE_BACKWARDS AST_DLLIST_TRAVERSE_BACKWARDS
+
+/*!
+  \brief Loops safely over (traverses) the entries in a list.
+  \param head This is a pointer to the list head structure
+  \param 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.
+  \param field This is the name of the field (declared using AST_DLLIST_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 \a for loop, and supplies the enclosed code with a pointer to each list
+  entry as it loops. It is typically used as follows:
+
+  \code
+  static AST_DLLIST_HEAD(entry_list, list_entry) entries;
+  ...
+  struct list_entry {
+  	...
+  	AST_DLLIST_ENTRY(list_entry) list;
+  }
+  ...
+  struct list_entry *current;
+  ...
+  AST_DLLIST_TRAVERSE_SAFE_BEGIN(&entries, current, list) {
+     (do something with current here)
+  }
+  AST_DLLIST_TRAVERSE_SAFE_END;
+  \endcode
+
+  It differs from AST_DLLIST_TRAVERSE() in that the code inside the loop can modify
+  (or even free, after calling AST_DLLIST_REMOVE_CURRENT()) the entry pointed to by
+  the \a current pointer without affecting the loop traversal.
+*/
+#define AST_DLLIST_TRAVERSE_SAFE_BEGIN(head, var, field) {				\
+	typeof((head)) __list_head = head;						\
+	typeof(__list_head->first) __list_next;						\
+	typeof(__list_head->first) __list_prev = NULL;					\
+	typeof(__list_head->first) __new_prev = NULL;					\
+	for ((var) = __list_head->first, __new_prev = (var),				\
+	      __list_next = (var) ? (var)->field.next : NULL;				\
+	     (var);									\
+	     __list_prev = __new_prev, (var) = __list_next,				\
+	     __new_prev = (var),							\
+	     __list_next = (var) ? (var)->field.next : NULL				\
+	    )
+
+#define AST_RWDLLIST_TRAVERSE_SAFE_BEGIN AST_DLLIST_TRAVERSE_SAFE_BEGIN
+
+/*!
+  \brief Loops safely over (traverses) the entries in a list.
+  \param head This is a pointer to the list head structure
+  \param 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.
+  \param field This is the name of the field (declared using AST_DLLIST_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 \a for loop, and supplies the enclosed code with a pointer to each list
+  entry as it loops. It is typically used as follows:
+
+  \code
+  static AST_DLLIST_HEAD(entry_list, list_entry) entries;
+  ...
+  struct list_entry {
+  	...
+  	AST_DLLIST_ENTRY(list_entry) list;
+  }
+  ...
+  struct list_entry *current;
+  ...
+  AST_DLLIST_TRAVERSE_SAFE_BEGIN(&entries, current, list) {
+     (do something with current here)
+  }
+  AST_DLLIST_TRAVERSE_SAFE_END;
+  \endcode
+
+  It differs from AST_DLLIST_TRAVERSE() in that the code inside the loop can modify
+  (or even free, after calling AST_DLLIST_REMOVE_CURRENT()) the entry pointed to by
+  the \a current pointer without affecting the loop traversal.
+*/
+#define AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN(head, var, field) {				\
+	typeof((head)) __list_head = head;						\
+	typeof(__list_head->first) __list_next;						\
+	typeof(__list_head->first) __list_prev = NULL;					\
+	typeof(__list_head->first) __new_prev = NULL;					\
+	for ((var) = __list_head->last, __new_prev = (var),				\
+			 __list_next = NULL, __list_prev = (var) ? (var)->field.prev : NULL;	\
+	     (var);									\
+	     __list_next = __new_prev, (var) = __list_prev,				\
+	     __new_prev = (var),							\
+	     __list_prev = (var) ? (var)->field.prev : NULL				\
+	    )
+
+#define AST_RWDLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN
+
+/*!
+  \brief Removes the \a current entry from a list during a traversal.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+
+  \note This macro can \b only be used inside an AST_DLLIST_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).
+ */
+#define AST_DLLIST_REMOVE_CURRENT(field) do {			\
+	__new_prev->field.next = NULL;						\
+	__new_prev->field.prev = NULL;						\
+	if (__list_next)									\
+		__new_prev = __list_prev;						\
+	else												\
+		__new_prev = NULL;								\
+	if (__list_prev) {                                  \
+		if (__list_next)								\
+			__list_next->field.prev = __list_prev;		\
+		__list_prev->field.next = __list_next;			\
+	} else {                                            \
+		__list_head->first = __list_next;				\
+		if (__list_next)								\
+			__list_next->field.prev = NULL;				\
+	}													\
+	if (!__list_next)									\
+		__list_head->last = __list_prev; 				\
+	} while (0)
+
+#define AST_RWDLLIST_REMOVE_CURRENT AST_DLLIST_REMOVE_CURRENT
+
+#define AST_DLLIST_MOVE_CURRENT(newhead, field) do { \
+	typeof ((newhead)->first) __list_cur = __new_prev;				\
+	AST_DLLIST_REMOVE_CURRENT(field);							\
+	AST_DLLIST_INSERT_TAIL((newhead), __list_cur, field);				\
+	} while (0)
+
+#define AST_RWDLLIST_MOVE_CURRENT AST_DLLIST_MOVE_CURRENT
+
+#define AST_DLLIST_MOVE_CURRENT_BACKWARDS(newhead, field) do { \
+	typeof ((newhead)->first) __list_cur = __new_prev;			\
+	if (!__list_next) {											\
+		AST_DLLIST_REMOVE_CURRENT(field);						\
+		__new_prev = NULL;										\
+		AST_DLLIST_INSERT_HEAD((newhead), __list_cur, field);	\
+	} else {													\
+		AST_DLLIST_REMOVE_CURRENT(field);						\
+		AST_DLLIST_INSERT_HEAD((newhead), __list_cur, field);	\
+	}} while (0)
+
+#define AST_RWDLLIST_MOVE_CURRENT_BACKWARDS AST_DLLIST_MOVE_CURRENT
+
+/*!
+  \brief Inserts a list entry before the current entry during a traversal.
+  \param elm This is a pointer to the entry to be inserted.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+
+  \note This macro can \b only be used inside an AST_DLLIST_TRAVERSE_SAFE_BEGIN()
+  block.
+ */
+#define AST_DLLIST_INSERT_BEFORE_CURRENT(elm, field) do {	\
+	if (__list_prev) {										\
+		(elm)->field.next = __list_prev->field.next;		\
+		(elm)->field.prev = __list_prev;					\
+		if (__list_prev->field.next)                        \
+			__list_prev->field.next->field.prev = (elm);	\
+		__list_prev->field.next = (elm);					\
+	} else {												\
+		(elm)->field.next = __list_head->first;			\
+		__list_head->first->field.prev = (elm);			\
+		(elm)->field.prev = NULL;						\
+		__list_head->first = (elm);						\
+	}													\
+} while (0)
+
+#define AST_RWDLLIST_INSERT_BEFORE_CURRENT AST_DLLIST_INSERT_BEFORE_CURRENT
+
+/*!
+  \brief Inserts a list entry after the current entry during a backwards traversal. Since
+         this is a backwards traversal, this will insert the entry AFTER the current
+         element. Since this is a backwards traveral, though, this would be BEFORE
+         the current entry in traversal order. Confusing? 
+  \param elm This is a pointer to the entry to be inserted.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+
+  \note This macro can \b only be used inside an AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_BEGIN()
+  block. If you use this with the AST_DLLIST_TRAVERSE_SAFE_BEGIN(), be prepared for
+  strange things!
+ */
+#define AST_DLLIST_INSERT_BEFORE_CURRENT_BACKWARDS(elm, field) do {			\
+	if (__list_next) {								\
+		(elm)->field.next = __list_next;			\
+		(elm)->field.prev = __new_prev;				\
+		__new_prev->field.next = (elm);	   			\
+		__list_next->field.prev = (elm);	   		\
+	} else {										\
+		(elm)->field.prev = __list_head->last;		\
+		(elm)->field.next = NULL;					\
+		__list_head->last->field.next = (elm);		\
+		__list_head->last = (elm);					\
+	}												\
+} while (0)
+
+#define AST_RWDLLIST_INSERT_BEFORE_CURRENT_BACKWARDS AST_DLLIST_INSERT_BEFORE_CURRENT_BACKWARDS
+
+/*!
+  \brief Closes a safe loop traversal block.
+ */
+#define AST_DLLIST_TRAVERSE_SAFE_END  }
+
+#define AST_RWDLLIST_TRAVERSE_SAFE_END AST_DLLIST_TRAVERSE_SAFE_END
+
+/*!
+  \brief Closes a safe loop traversal block.
+ */
+#define AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_END  }
+
+#define AST_RWDLLIST_TRAVERSE_BACKWARDS_SAFE_END AST_DLLIST_TRAVERSE_BACKWARDS_SAFE_END
+
+/*!
+  \brief Initializes a list head structure.
+  \param head This is a pointer to the list head structure
+
+  This macro initializes a list head structure by setting the head
+  entry to \a NULL (empty list) and recreating the embedded lock.
+*/
+#define AST_DLLIST_HEAD_INIT(head) {					\
+	(head)->first = NULL;						\
+	(head)->last = NULL;						\
+	ast_mutex_init(&(head)->lock);					\
+}
+
+/*!
+  \brief Initializes an rwlist head structure.
+  \param head This is a pointer to the list head structure
+
+  This macro initializes a list head structure by setting the head
+  entry to \a NULL (empty list) and recreating the embedded lock.
+*/
+#define AST_RWDLLIST_HEAD_INIT(head) {                                    \
+        (head)->first = NULL;                                           \
+        (head)->last = NULL;                                            \
+        ast_rwlock_init(&(head)->lock);                                 \
+}
+
+/*!
+  \brief Destroys a list head structure.
+  \param head This is a pointer to the list head structure
+
+  This macro destroys a list head structure by setting the head
+  entry to \a NULL (empty list) and destroying the embedded lock.
+  It does not free the structure from memory.
+*/
+#define AST_DLLIST_HEAD_DESTROY(head) {					\
+	(head)->first = NULL;						\
+	(head)->last = NULL;						\
+	ast_mutex_destroy(&(head)->lock);				\
+}
+
+/*!
+  \brief Destroys an rwlist head structure.
+  \param head This is a pointer to the list head structure
+
+  This macro destroys a list head structure by setting the head
+  entry to \a NULL (empty list) and destroying the embedded lock.
+  It does not free the structure from memory.
+*/
+#define AST_RWDLLIST_HEAD_DESTROY(head) {                                 \
+        (head)->first = NULL;                                           \
+        (head)->last = NULL;                                            \
+        ast_rwlock_destroy(&(head)->lock);                              \
+}
+
+/*!
+  \brief Initializes a list head structure.
+  \param head This is a pointer to the list head structure
+
+  This macro initializes a list head structure by setting the head
+  entry to \a NULL (empty list). There is no embedded lock handling
+  with this macro.
+*/
+#define AST_DLLIST_HEAD_INIT_NOLOCK(head) {				\
+	(head)->first = NULL;						\
+	(head)->last = NULL;						\
+}
+
+/*!
+  \brief Inserts a list entry after a given entry.
+  \param head This is a pointer to the list head structure
+  \param listelm This is a pointer to the entry after which the new entry should
+  be inserted.
+  \param elm This is a pointer to the entry to be inserted.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+ */
+#define AST_DLLIST_INSERT_AFTER(head, listelm, elm, field) do {		\
+	(elm)->field.next = (listelm)->field.next;			\
+	(elm)->field.prev = (listelm);			\
+	if ((listelm)->field.next)				\
+		(listelm)->field.next->field.prev = (elm);	\
+	(listelm)->field.next = (elm);					\
+	if ((head)->last == (listelm))					\
+		(head)->last = (elm);					\
+} while (0)
+
+#define AST_RWDLLIST_INSERT_AFTER AST_DLLIST_INSERT_AFTER
+
+/*!
+  \brief Inserts a list entry before a given entry.
+  \param head This is a pointer to the list head structure
+  \param listelm This is a pointer to the entry before which the new entry should
+  be inserted.
+  \param elm This is a pointer to the entry to be inserted.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+ */
+#define AST_DLLIST_INSERT_BEFORE(head, listelm, elm, field) do {		\
+	(elm)->field.next = (listelm);			\
+	(elm)->field.prev = (listelm)->field.prev;			\
+	if ((listelm)->field.prev)				\
+		(listelm)->field.prev->field.next = (elm);	\
+	(listelm)->field.prev = (elm);					\
+	if ((head)->first == (listelm))					\
+		(head)->first = (elm);					\
+} while (0)
+
+#define AST_RWDLLIST_INSERT_BEFORE AST_DLLIST_INSERT_BEFORE
+
+/*!
+  \brief Inserts a list entry at the head of a list.
+  \param head This is a pointer to the list head structure
+  \param elm This is a pointer to the entry to be inserted.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+ */
+#define AST_DLLIST_INSERT_HEAD(head, elm, field) do {			\
+		(elm)->field.next = (head)->first;			\
+		if ((head)->first)                          \
+			(head)->first->field.prev = (elm);			\
+		(elm)->field.prev = NULL;			\
+		(head)->first = (elm);					\
+		if (!(head)->last)					\
+			(head)->last = (elm);				\
+} while (0)
+
+#define AST_RWDLLIST_INSERT_HEAD AST_DLLIST_INSERT_HEAD
+
+/*!
+  \brief Appends a list entry to the tail of a list.
+  \param head This is a pointer to the list head structure
+  \param elm This is a pointer to the entry to be appended.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+
+  Note: The link field in the appended entry is \b not modified, so if it is
+  actually the head of a list itself, the entire list will be appended
+  temporarily (until the next AST_DLLIST_INSERT_TAIL is performed).
+ */
+#define AST_DLLIST_INSERT_TAIL(head, elm, field) do {	\
+      if (!(head)->first) {						\
+		(head)->first = (elm);					\
+		(head)->last = (elm);                   \
+		(elm)->field.next = NULL;				\
+		(elm)->field.prev = NULL;				\
+      } else {									\
+		(head)->last->field.next = (elm);		\
+		(elm)->field.prev = (head)->last;		\
+		(elm)->field.next = NULL;				\
+		(head)->last = (elm);					\
+      }											\
+} while (0)
+
+#define AST_RWDLLIST_INSERT_TAIL AST_DLLIST_INSERT_TAIL
+
+/*!
+  \brief Appends a whole list to the tail of a list.
+  \param head This is a pointer to the list head structure
+  \param list This is a pointer to the list to be appended.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+
+  Note: The source list (the \a list parameter) will be empty after
+  calling this macro (the list entries are \b moved to the target list).
+ */
+#define AST_DLLIST_APPEND_DLLIST(head, list, field) do {			\
+      if (!(head)->first) {						\
+		(head)->first = (list)->first;				\
+		(head)->last = (list)->last;				\
+      } else {								\
+		(head)->last->field.next = (list)->first;		\
+		(list)->first->field.prev = (head)->last;		\
+		(head)->last = (list)->last;				\
+      }									\
+      (list)->first = NULL;						\
+      (list)->last = NULL;						\
+} while (0)
+
+#define AST_RWDLLIST_APPEND_DLLIST AST_DLLIST_APPEND_DLLIST
+
+/*!
+  \brief Removes and returns the head entry from a list.
+  \param head This is a pointer to the list head structure
+  \param field This is the name of the field (declared using AST_DLLIST_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.
+ */
+#define AST_DLLIST_REMOVE_HEAD(head, field) ({				\
+		typeof((head)->first) cur = (head)->first;		\
+		if (cur) {						\
+			(head)->first = cur->field.next;		\
+			if (cur->field.next)                \
+				cur->field.next->field.prev = NULL;	\
+			cur->field.next = NULL;				\
+			if ((head)->last == cur)			\
+				(head)->last = NULL;			\
+		}							\
+		cur;							\
+	})
+
+#define AST_RWDLLIST_REMOVE_HEAD AST_DLLIST_REMOVE_HEAD
+
+/*!
+  \brief Removes a specific entry from a list.
+  \param head This is a pointer to the list head structure
+  \param elm This is a pointer to the entry to be removed.
+  \param field This is the name of the field (declared using AST_DLLIST_ENTRY())
+  used to link entries of this list together.
+  \warning The removed entry is \b not freed nor modified in any way.
+ */
+#define AST_DLLIST_REMOVE(head, elm, field) ({			        \
+	__typeof(elm) __res = (elm);						\
+	if ((head)->first == (elm)) {								\
+		(head)->first = (elm)->field.next;						\
+		if ((elm)->field.next)									\
+			(elm)->field.next->field.prev = NULL;				\
+		if ((head)->last == (elm))								\
+			(head)->last = NULL;								\
+	} else {														\
+		(elm)->field.prev->field.next = (elm)->field.next;			\
+		if ((elm)->field.next)											\
+			(elm)->field.next->field.prev = (elm)->field.prev;			\
+		if ((head)->last == (elm))										\
+			(head)->last = (elm)->field.prev;							\
+	}																	\
+	(elm)->field.next = NULL;											\
+	(elm)->field.prev = NULL;											\
+	(__res);															\
+})
+
+#define AST_RWDLLIST_REMOVE AST_DLLIST_REMOVE
+
+#endif /* _ASTERISK_DLINKEDLISTS_H */