Make ast_taskprocessor_listener opaque.
[asterisk/asterisk.git] / include / asterisk / taskprocessor.h
index 7720547..a26cf43 100644 (file)
@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2007-2008, Digium, Inc.
+ * Copyright (C) 2007-2013, Digium, Inc.
  *
  * Dwayne M. Hubbard <dhubbard@digium.com>
  *
  *
  * Dwayne M. Hubbard <dhubbard@digium.com>
  *
@@ -22,7 +22,7 @@
  *
  * \author Dwayne M. Hubbard <dhubbard@digium.com>
  *
  *
  * \author Dwayne M. Hubbard <dhubbard@digium.com>
  *
- * \note A taskprocessor is a named singleton containing a task queue that
+ * \note A taskprocessor is a named object containing a task queue that
  * serializes tasks pushed into it by [a] module(s) that reference the taskprocessor.
  * A taskprocessor is created the first time its name is requested via the
  * ast_taskprocessor_get() function or the ast_taskprocessor_create_with_listener()
  * serializes tasks pushed into it by [a] module(s) that reference the taskprocessor.
  * A taskprocessor is created the first time its name is requested via the
  * ast_taskprocessor_get() function or the ast_taskprocessor_create_with_listener()
@@ -75,17 +75,6 @@ struct ast_taskprocessor_listener;
 
 struct ast_taskprocessor_listener_callbacks {
        /*!
 
 struct ast_taskprocessor_listener_callbacks {
        /*!
-        * \brief Allocate the listener's private data
-        *
-        * This is called during taskprocesor creation.
-        * It is not necessary to assign the private data to the listener.
-        *
-        * \param listener The listener to which the private data belongs
-        * \retval NULL Error while attempting to initialize private data
-        * \retval non-NULL Allocated private data
-        */
-       void *(*alloc)(struct ast_taskprocessor_listener *listener);
-       /*!
         * \brief The taskprocessor has started completely
         *
         * This indicates that the taskprocessor is fully set up and the listener
         * \brief The taskprocessor has started completely
         *
         * This indicates that the taskprocessor is fully set up and the listener
@@ -111,7 +100,8 @@ struct ast_taskprocessor_listener_callbacks {
         * \brief Indicates the taskprocessor wishes to die.
         *
         * All operations on the task processor must to be stopped in
         * \brief Indicates the taskprocessor wishes to die.
         *
         * All operations on the task processor must to be stopped in
-        * this callback.
+        * this callback. This is an opportune time to free the listener's
+        * user data if it is not going to be used anywhere else.
         *
         * After this callback returns, it is NOT safe to operate on the
         * listener's reference to the taskprocessor.
         *
         * After this callback returns, it is NOT safe to operate on the
         * listener's reference to the taskprocessor.
@@ -119,35 +109,10 @@ struct ast_taskprocessor_listener_callbacks {
         * \param listener The listener
         */
        void (*shutdown)(struct ast_taskprocessor_listener *listener);
         * \param listener The listener
         */
        void (*shutdown)(struct ast_taskprocessor_listener *listener);
-       /*!
-        * \brief Destroy the listener's private data
-        *
-        * It is required that you free the private data in this callback
-        * in addition to the private data's individual fields.
-        *
-        * \param private_data The listener's private data
-        */
-       void (*destroy)(void *private_data);
 };
 
 };
 
-/*!
- * \brief A listener for taskprocessors
- *
- * \since 12.0.0
- *
- * When a taskprocessor's state changes, the listener
- * is notified of the change. This allows for tasks
- * to be addressed in whatever way is appropriate for
- * the module using the taskprocessor.
- */
-struct ast_taskprocessor_listener {
-       /*! The callbacks the taskprocessor calls into to notify of state changes */
-       const struct ast_taskprocessor_listener_callbacks *callbacks;
-       /*! The taskprocessor that the listener is listening to */
-       struct ast_taskprocessor *tps;
-       /*! Data private to the listener */
-       void *private_data;
-};
+struct ast_taskprocessor *ast_taskprocessor_listener_get_tps(const struct ast_taskprocessor_listener *listener);
+void *ast_taskprocessor_listener_get_user_data(const struct ast_taskprocessor_listener *listener);
 
 /*!
  * \brief Allocate a taskprocessor listener
 
 /*!
  * \brief Allocate a taskprocessor listener
@@ -158,10 +123,11 @@ struct ast_taskprocessor_listener {
  * callbacks.
  *
  * \param callbacks The callbacks to assign to the listener
  * callbacks.
  *
  * \param callbacks The callbacks to assign to the listener
+ * \param user_data The user data for the listener
  * \retval NULL Failure
  * \retval non-NULL The newly allocated taskprocessor listener
  */
  * \retval NULL Failure
  * \retval non-NULL The newly allocated taskprocessor listener
  */
-struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks);
+struct ast_taskprocessor_listener *ast_taskprocessor_listener_alloc(const struct ast_taskprocessor_listener_callbacks *callbacks, void *user_data);
 
 /*!
  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary
 
 /*!
  * \brief Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary