Closed #1420: Add support for event manager

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@3893 74dad513-b988-da41-8d7b-12977e46ad98

6 files changed, 122 insertions, 177 deletions

diff --git a/pjmedia/include/pjmedia-videodev/videodev.h b/pjmedia/include/pjmedia-videodev/videodev.h
index 767fdf73..fa6c2697 100644
--- a/pjmedia/include/pjmedia-videodev/videodev.h
+++ b/pjmedia/include/pjmedia-videodev/videodev.h
@@ -751,19 +751,6 @@ PJ_DECL(pj_bool_t) pjmedia_vid_dev_stream_is_running(pjmedia_vid_dev_stream *str
 
 
 /**
- * Get the event publisher object for the video stream. Caller typically use
- * the returned object to subscribe or unsubscribe events from the video
- * stream.
- *
- * @param strm      The video stream.
- *
- * @return          The event publisher object.
- */
-PJ_DECL(pjmedia_event_publisher*)
-pjmedia_vid_dev_stream_get_event_publisher(pjmedia_vid_dev_stream *strm);
-
-
-/**
  * Request one frame from the stream. Application needs to call this function
  * periodically only if the stream doesn't support "active interface", i.e.
  * the pjmedia_vid_dev_info.has_callback member is PJ_FALSE.
diff --git a/pjmedia/include/pjmedia-videodev/videodev_imp.h b/pjmedia/include/pjmedia-videodev/videodev_imp.h
index 8ddfd968..0a1d9830 100644
--- a/pjmedia/include/pjmedia-videodev/videodev_imp.h
+++ b/pjmedia/include/pjmedia-videodev/videodev_imp.h
@@ -188,9 +188,6 @@ struct pjmedia_vid_dev_stream
 
     /** Operations */
     pjmedia_vid_dev_stream_op *op;
-
-    /** Event producer */
-    pjmedia_event_publisher	epub;
 };
 
 
diff --git a/pjmedia/include/pjmedia/event.h b/pjmedia/include/pjmedia/event.h
index 259f7264..7a779e79 100644
--- a/pjmedia/include/pjmedia/event.h
+++ b/pjmedia/include/pjmedia/event.h
@@ -25,7 +25,6 @@
  */
 #include <pjmedia/format.h>
 #include <pjmedia/signatures.h>
-#include <pj/list.h>
 
 PJ_BEGIN_DECL
 
@@ -88,16 +87,6 @@ typedef enum pjmedia_event_type
 } pjmedia_event_type;
 
 /**
- * Forward declaration for event subscription.
- */
-typedef struct pjmedia_event_subscription pjmedia_event_subscription;
-
-/**
- * Forward declaration for event publisher.
- */
-typedef struct pjmedia_event_publisher pjmedia_event_publisher;
-
-/**
  * Additional data/parameters for media format changed event
  * (PJMEDIA_EVENT_FMT_CHANGED).
  */
@@ -162,8 +151,8 @@ typedef char pjmedia_event_user_data[PJMEDIA_EVENT_DATA_MAX_SIZE];
 
 /**
  * This structure describes a media event. It consists mainly of the event
- * type and additional data/parameters for the event. Event publishers need
- * to use #pjmedia_event_init() to initialize this event structure with
+ * type and additional data/parameters for the event. Applications can
+ * use #pjmedia_event_init() to initialize this event structure with
  * basic information about the event.
  */
 typedef struct pjmedia_event
@@ -179,27 +168,22 @@ typedef struct pjmedia_event
     pj_timestamp		 	 timestamp;
 
     /**
-     * This keeps count on the number of subscribers that have
-     * processed this event.
-     */
-    unsigned				 proc_cnt;
-
-    /**
-     * The object signature of the event publisher. Application may use
-     * this to check which publisher published the event.
+     * Pointer information about the source of this event. This field
+     * is provided mainly for comparison purpose so that event subscribers
+     * can check which source the event originated from. Usage of this
+     * pointer for other purpose may require special care such as mutex
+     * locking or checking whether the object is already destroyed.
      */
-    pjmedia_obj_sig			 epub_sig;
+    const void	                        *src;
 
     /**
-     * Pointer information about the source of this event. This field
-     * is provided mainly so that the event subscribers can compare it
-     * against the publisher that it subscribed the events from initially,
-     * a publisher can republish events from other publisher. Event
-     * subscription must be careful when using this pointer other than for
-     * comparison purpose, since access to the publisher may require special
-     * care (e.g. mutex locking).
+     * Pointer information about the publisher of this event. This field
+     * is provided mainly for comparison purpose so that event subscribers
+     * can check which object published the event. Usage of this
+     * pointer for other purpose may require special care such as mutex
+     * locking or checking whether the object is already destroyed.
      */
-    const pjmedia_event_publisher	*epub;
+    const void	                        *epub;
 
     /**
      * Additional data/parameters about the event. The type of data
@@ -238,164 +222,170 @@ typedef struct pjmedia_event
 } pjmedia_event;
 
 /**
- * The callback to receive media events. The callback should increase
- * \a proc_cnt field of the event if it processes the event.
+ * The callback to receive media events.
  *
- * @param esub		The subscription that was made initially to receive
- * 			this event.
- * @param event		The media event itself.
+ * @param event		The media event.
+ * @param user_data	The user data associated with the callback.
  *
  * @return		If the callback returns non-PJ_SUCCESS, this return
- * 			code may be propagated back to the producer.
+ * 			code may be propagated back to the caller.
  */
-typedef pj_status_t pjmedia_event_cb(pjmedia_event_subscription *esub,
-				     pjmedia_event *event);
+typedef pj_status_t pjmedia_event_cb(pjmedia_event *event,
+                                     void *user_data);
 
 /**
- * This structure keeps the data needed to maintain an event subscription.
- * This data is normally kept by event publishers.
+ * This enumeration describes flags for event publication via
+ * #pjmedia_event_publish().
  */
-struct pjmedia_event_subscription
+typedef enum pjmedia_event_publish_flag
 {
-    /** Standard list members */
-    PJ_DECL_LIST_MEMBER(pjmedia_event_subscription);
+    /**
+     * Publisher will only post the event to the event manager. It is the
+     * event manager that will later notify all the publisher's subscribers.
+     */
+    PJMEDIA_EVENT_PUBLISH_POST_EVENT = 1
 
-    /** Callback that will be called by publisher to report events. */
-    pjmedia_event_cb	*cb;
+} pjmedia_event_publish_flag;
 
-    /** User data for this subscription */
-    void		*user_data;
+/**
+ * Event manager flag.
+ */
+typedef enum pjmedia_event_mgr_flag
+{
+    /**
+     * Tell the event manager not to create any event worker thread.
+     */
+    PJMEDIA_EVENT_MGR_NO_THREAD = 1
 
-    /** Current publisher it is subscribed to */
-    pjmedia_event_publisher *subscribe_to;
-};
+} pjmedia_event_mgr_flag;
 
 /**
- * This describes an event publisher. An event publisher is an object that
- * maintains event subscriptions. When an event is published on behalf of
- * a publisher with #pjmedia_event_publish(), that event will be propagated
- * to all of the subscribers registered to the publisher.
+ * Opaque data type for event manager. Typically, the event manager
+ * is a singleton instance, although application may instantiate more than one
+ * instances of this if required.
  */
-struct pjmedia_event_publisher
-{
-    /** The object signature of the publisher */
-    pjmedia_obj_sig		sig;
+typedef struct pjmedia_event_mgr pjmedia_event_mgr;
 
-    /** List of subscriptions for this event publisher */
-    pjmedia_event_subscription	subscription_list;
-};
+/**
+ * Create a new event manager instance. This will also set the pointer
+ * to the singleton instance if the value is still NULL.
+ *
+ * @param pool		Pool to allocate memory from.
+ * @param options       Options. Bitmask flags from #pjmedia_event_mgr_flag
+ * @param mgr		Pointer to hold the created instance of the
+ * 			event manager.
+ *
+ * @return		PJ_SUCCESS on success or the appropriate error code.
+ */
+PJ_DECL(pj_status_t) pjmedia_event_mgr_create(pj_pool_t *pool,
+                                              unsigned options,
+				              pjmedia_event_mgr **mgr);
 
 /**
- * Initialize event structure with basic data about the event.
+ * Get the singleton instance of the event manager.
  *
- * @param event		The event to be initialized.
- * @param type		The event type to be set for this event.
- * @param ts		Event timestamp. May be set to NULL to set the event
- * 			timestamp to zero.
- * @param epub		Event publisher.
+ * @return		The instance.
  */
-PJ_DECL(void) pjmedia_event_init(pjmedia_event *event,
-                                 pjmedia_event_type type,
-                                 const pj_timestamp *ts,
-                                 const pjmedia_event_publisher *epub);
+PJ_DECL(pjmedia_event_mgr*) pjmedia_event_mgr_instance(void);
 
 /**
- * Initialize an event publisher structure.
+ * Manually assign a specific event manager instance as the singleton
+ * instance. Normally this is not needed if only one instance is ever
+ * going to be created, as the library automatically assign the singleton
+ * instance.
  *
- * @param epub		The event publisher.
- * @param sig		The object signature of the publisher.
+ * @param mgr		The instance to be used as the singleton instance.
+ * 			Application may specify NULL to clear the singleton
+ * 			singleton instance.
  */
-PJ_DECL(void) pjmedia_event_publisher_init(pjmedia_event_publisher *epub,
-                                           pjmedia_obj_sig sig);
+PJ_DECL(void) pjmedia_event_mgr_set_instance(pjmedia_event_mgr *mgr);
 
 /**
- * Initialize subscription data.
+ * Destroy an event manager. If the manager happens to be the singleton
+ * instance, the singleton instance will be set to NULL.
  *
- * @param esub		The event subscription.
- * @param cb		The callback to receive events.
- * @param user_data	Arbitrary user data to be associated with the
- * 			subscription.
+ * @param mgr		The eventmanager. Specify NULL to use
+ * 			the singleton instance.
  */
-PJ_DECL(void) pjmedia_event_subscription_init(pjmedia_event_subscription *esub,
-                                              pjmedia_event_cb *cb,
-                                              void *user_data);
+PJ_DECL(void) pjmedia_event_mgr_destroy(pjmedia_event_mgr *mgr);
 
 /**
- * Subscribe to events published by the specified publisher using the
- * specified subscription object. The callback and user data fields of
- * the subscription object must have been initialized prior to calling
- * this function, and the subscription object must be kept alive throughout
- * the duration of the subscription (e.g. it must not be allocated from
- * the stack).
+ * Initialize event structure with basic data about the event.
  *
- * Note that the subscriber may receive not only events emitted by
+ * @param event		The event to be initialized.
+ * @param type		The event type to be set for this event.
+ * @param ts		Event timestamp. May be set to NULL to set the event
+ * 			timestamp to zero.
+ * @param src		Event source.
+ */
+PJ_DECL(void) pjmedia_event_init(pjmedia_event *event,
+                                 pjmedia_event_type type,
+                                 const pj_timestamp *ts,
+                                 const void *src);
+
+/**
+ * Subscribe a callback function to events published by the specified
+ * publisher. Note that the subscriber may receive not only events emitted by
  * the specific publisher specified in the argument, but also from other
  * publishers contained by the publisher, if the publisher is republishing
  * events from other publishers.
  *
+ * @param mgr		The event manager.
+ * @param pool          Pool to allocate memory from.
+ * @param cb            The callback function to receive the event.
+ * @param user_data     The user data to be associated with the callback
+ *                      function.
  * @param epub		The event publisher.
- * @param esub 		The event subscription object.
  *
  * @return		PJ_SUCCESS on success or the appropriate error code.
  */
-PJ_DECL(pj_status_t) pjmedia_event_subscribe(pjmedia_event_publisher *epub,
-                                             pjmedia_event_subscription *esub);
+PJ_DECL(pj_status_t) pjmedia_event_subscribe(pjmedia_event_mgr *mgr,
+                                             pj_pool_t *pool,
+                                             pjmedia_event_cb *cb,
+                                             void *user_data,
+                                             void *epub);
 
 /**
- * Unsubscribe the specified subscription object from publisher it is
- * currently subscribed to. If the subscription object is not currently
- * subscribed to anything, the function will do nothing.
+ * Unsubscribe the callback associated with the user data from a publisher.
+ * If the user data is not specified, this function will do the
+ * unsubscription for all user data. If the publisher, epub, is not
+ * specified, this function will do the unsubscription from all publishers.
  *
- * @param esub		The event subscription object, which must be the same
- * 			object that was given to #pjmedia_event_subscribe().
+ * @param mgr		The event manager.
+ * @param cb            The callback function.
+ * @param user_data     The user data associated with the callback
+ *                      function, can be NULL.
+ * @param epub		The event publisher, can be NULL.
  *
  * @return		PJ_SUCCESS on success or the appropriate error code.
  */
 PJ_DECL(pj_status_t)
-pjmedia_event_unsubscribe(pjmedia_event_subscription *esub);
-
-/**
- * Check if the specified publisher has subscribers.
- *
- * @param epub		The event publisher.
- *
- * @return		PJ_TRUE if the publisher has at least one subscriber.
- */
-PJ_DECL(pj_bool_t)
-pjmedia_event_publisher_has_sub(pjmedia_event_publisher *epub);
+pjmedia_event_unsubscribe(pjmedia_event_mgr *mgr,
+                          pjmedia_event_cb *cb,
+                          void *user_data,
+                          void *epub);
 
 /**
  * Publish the specified event to all subscribers of the specified event
- * publisher.
+ * publisher. By default, the function will call all the subcribers'
+ * callbacks immediately. If the publisher uses the flag
+ * PJMEDIA_EVENT_PUBLISH_POST_EVENT, publisher will only post the event
+ * to the event manager and return immediately. It is the event manager
+ * that will later notify all the publisher's subscribers.
  *
+ * @param mgr		The event manager.
  * @param epub		The event publisher.
  * @param event		The event to be published.
+ * @param flag          Publication flag.
  *
  * @return		PJ_SUCCESS only if all subscription callbacks returned
  * 			PJ_SUCCESS.
  */
-PJ_DECL(pj_status_t) pjmedia_event_publish(pjmedia_event_publisher *epub,
-                                           pjmedia_event *event);
+PJ_DECL(pj_status_t) pjmedia_event_publish(pjmedia_event_mgr *mgr,
+                                           void *epub,
+                                           pjmedia_event *event,
+                                           pjmedia_event_publish_flag flag);
 
-/**
- * Subscribe to events produced by the source publisher in \a esrc and
- * republish the events to all subscribers in \a epub publisher.
- *
- * @param esrc		The event source from which events will be
- * 			republished.
- * @param epub		Events from the event source above will be
- * 			republished to subscribers of this publisher.
- * @param esub		The subscription object to be used to subscribe
- * 			to \a esrc. This doesn't need to be initialized,
- * 			but it must be kept alive throughout the lifetime
- * 			of the subsciption.
- *
- * @return		PJ_SUCCESS only if all subscription callbacks returned
- * 			PJ_SUCCESS.
- */
-PJ_DECL(pj_status_t) pjmedia_event_republish(pjmedia_event_publisher *esrc,
-                                             pjmedia_event_publisher *epub,
-                                             pjmedia_event_subscription *esub);
 
 /**
  * @}  PJMEDIA_EVENT
diff --git a/pjmedia/include/pjmedia/port.h b/pjmedia/include/pjmedia/port.h
index b6493413..4ea5de1d 100644
--- a/pjmedia/include/pjmedia/port.h
+++ b/pjmedia/include/pjmedia/port.h
@@ -399,11 +399,6 @@ typedef struct pjmedia_port
      */
     pj_status_t (*on_destroy)(struct pjmedia_port *this_port);
 
-    /**
-     * Get event publisher for this media port, if any.
-     */
-    pjmedia_event_publisher *(*get_event_pub)(struct pjmedia_port *this_port);
-
 } pjmedia_port;
 
 
@@ -484,17 +479,6 @@ PJ_DECL(pj_status_t) pjmedia_port_put_frame( pjmedia_port *port,
 					     pjmedia_frame *frame );
 
 /**
- * Get the event publisher for the media port, if any.
- *
- * @param port	    The media port.
- *
- * @return	    The event publisher, or NULL if the port does not publish
- * 		    events.
- */
-PJ_DECL(pjmedia_event_publisher*)
-pjmedia_port_get_event_publisher(pjmedia_port *port);
-
-/**
  * Destroy port (and subsequent downstream ports)
  *
  * @param port	    The media port.
diff --git a/pjmedia/include/pjmedia/vid_codec.h b/pjmedia/include/pjmedia/vid_codec.h
index 4726d2b2..9716e540 100644
--- a/pjmedia/include/pjmedia/vid_codec.h
+++ b/pjmedia/include/pjmedia/vid_codec.h
@@ -249,9 +249,6 @@ struct pjmedia_vid_codec
 
     /** Operations to codec. */
     pjmedia_vid_codec_op	*op;
-
-    /** Event publisher object */
-    pjmedia_event_publisher	 epub;
 };
 
 
diff --git a/pjmedia/include/pjmedia/vid_port.h b/pjmedia/include/pjmedia/vid_port.h
index 66c31c84..3de28346 100644
--- a/pjmedia/include/pjmedia/vid_port.h
+++ b/pjmedia/include/pjmedia/vid_port.h
@@ -105,16 +105,6 @@ PJ_DECL(void) pjmedia_vid_port_set_cb(pjmedia_vid_port *vid_port,
                                       void *user_data);
 
 /**
- * Get the event publisher instance of the video port.
- *
- * @param vid_port	The video port.
- *
- * @return		The event publisher of the video port.
- */
-PJ_DECL(pjmedia_event_publisher*)
-pjmedia_vid_port_get_event_publisher(pjmedia_vid_port *vid_port);
-
-/**
  * Return the underlying video stream of the video port.
  *
  * @param vid_port	The video port.