Make ast_taskprocessor_listener opaque.
[asterisk/asterisk.git] / include / asterisk / taskprocessor.h
index 6359c05..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,15 +75,14 @@ struct ast_taskprocessor_listener;
 
 struct ast_taskprocessor_listener_callbacks {
        /*!
 
 struct ast_taskprocessor_listener_callbacks {
        /*!
-        * \brief Allocate the listener's private data
+        * \brief The taskprocessor has started completely
         *
         *
-        * It is not necessary to assign the private data to the listener.
+        * This indicates that the taskprocessor is fully set up and the listener
+        * can now start interacting with it.
         *
         *
-        * \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
+        * \param listener The listener to start
         */
         */
-       void *(*alloc)(struct ast_taskprocessor_listener *listener);
+       int (*start)(struct ast_taskprocessor_listener *listener);
        /*!
         * \brief Indicates a task was pushed to the processor
         *
        /*!
         * \brief Indicates a task was pushed to the processor
         *
@@ -101,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.
@@ -109,47 +109,25 @@ 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
- *
- * 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);
 
 /*!
 
 /*!
- * Allocate a taskprocessor listener
+ * \brief Allocate a taskprocessor listener
+ *
+ * \since 12.0.0
  *
  * This will result in the listener being allocated with the specified
  *
  * This will result in the listener being allocated with the specified
- * callbacks. The listener's alloc() callback will be called to allocate
- * private data for the listener. The private data will be assigned to the
- * listener when the listener's alloc() function returns.
+ * callbacks.
  *
  * \param callbacks The callbacks to assign to the listener
  *
  * \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
@@ -168,6 +146,10 @@ struct ast_taskprocessor *ast_taskprocessor_get(const char *name, enum ast_tps_o
 /*!
  * \brief Create a taskprocessor with a custom listener
  *
 /*!
  * \brief Create a taskprocessor with a custom listener
  *
+ * \since 12.0.0
+ *
+ * The listener's alloc() and start() callbacks will be called during this function.
+ *
  * \param name The name of the taskprocessor to create
  * \param listener The listener for operations on this taskprocessor
  * \retval NULL Failure
  * \param name The name of the taskprocessor to create
  * \param listener The listener for operations on this taskprocessor
  * \retval NULL Failure
@@ -199,6 +181,9 @@ int ast_taskprocessor_push(struct ast_taskprocessor *tps, int (*task_exe)(void *
 
 /*!
  * \brief Pop a task off the taskprocessor and execute it.
 
 /*!
  * \brief Pop a task off the taskprocessor and execute it.
+ *
+ * \since 12.0.0
+ *
  * \param tps The taskprocessor from which to execute.
  * \retval 0 There is no further work to be done.
  * \retval 1 Tasks still remain in the taskprocessor queue.
  * \param tps The taskprocessor from which to execute.
  * \retval 0 There is no further work to be done.
  * \retval 1 Tasks still remain in the taskprocessor queue.