mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-18 14:26:43 +00:00
Code Issues 1 Projects Releases Wiki Activity

docs: standardize GstBus documentation

Browse source 
* Don't mention explicitly that API is MT safe, this implies that
  other API is not. GStreamer API is assumed to be MT safe, thread
  safety should only be explicitly mentioned when API is *not* MT safe

* Don't repeat what annotations are stating with respect to ownership
  transfer, nullability

* Document virtual methods and the class structure

* Misc cleanup / typo fixes / addition of links

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/753>
This commit is contained in:
Mathieu Duponchelle 2021-02-09 15:30:50 +01:00
parent 12639aad34
commit 5df982fd10
2 changed files with 61 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

109
gst/gstbus.c
View file

@ -35,7 +35,7 @@
* is done in another thread than the application.
*
* The GstBus provides support for #GSource based notifications. This makes it
* possible to handle the delivery in the glib mainloop.
* possible to handle the delivery in the glib #GMainLoop.
*
* The #GSource callback function gst_bus_async_signal_func() can be used to
* convert all bus messages into signal emissions.
@ -197,9 +197,9 @@ gst_bus_class_init (GstBusClass * klass)
gobject_class->constructed = gst_bus_constructed;
/**
* GstBus::enable-async:
* GstBus:enable-async:
*
* Enable async message delivery support for bus watches,
* Enables async message delivery support for bus watches,
* gst_bus_pop() and similar API. Without this only the
* synchronous message handlers are called.
*
@ -214,7 +214,7 @@ gst_bus_class_init (GstBusClass * klass)
/**
* GstBus::sync-message:
* @bus: the object which received the signal
* @self: the object which received the signal
* @message: the message that has been posted synchronously
*
* A message has been posted on the bus. This signal is emitted from the
@ -231,12 +231,12 @@ gst_bus_class_init (GstBusClass * klass)
/**
* GstBus::message:
* @bus: the object which received the signal
* @self: the object which received the signal
* @message: the message that has been posted asynchronously
*
* A message has been posted on the bus. This signal is emitted from a
* GSource added to the mainloop. this signal will only be emitted when
* there is a mainloop running.
* #GSource added to the mainloop. this signal will only be emitted when
* there is a #GMainLoop running.
*/
gst_bus_signals[ASYNC_MESSAGE] =
g_signal_new ("message", G_TYPE_FROM_CLASS (klass),
@ -320,12 +320,10 @@ gst_bus_new (void)
* @bus: a #GstBus to post on
* @message: (transfer full): the #GstMessage to post
*
* Post a message on the given bus. Ownership of the message
* Posts a message on the given bus. Ownership of the message
* is taken by the bus.
*
* Returns: %TRUE if the message could be posted, %FALSE if the bus is flushing.
*
* MT safe.
*/
gboolean
gst_bus_post (GstBus * bus, GstMessage * message)
@ -445,13 +443,11 @@ is_flushing:
* gst_bus_have_pending:
* @bus: a #GstBus to check
*
* Check if there are pending messages on the bus that
* Checks if there are pending messages on the bus that
* should be handled.
*
* Returns: %TRUE if there are messages on the bus to be handled, %FALSE
* otherwise.
*
* MT safe.
*/
gboolean
gst_bus_have_pending (GstBus * bus)
@ -471,11 +467,9 @@ gst_bus_have_pending (GstBus * bus)
* @bus: a #GstBus
* @flushing: whether or not to flush the bus
*
* If @flushing, flush out and unref any messages queued in the bus. Releases
* If @flushing, flushes out and unrefs any messages queued in the bus. Releases
* references to the message origin objects. Will flush future messages until
* gst_bus_set_flushing() sets @flushing to %FALSE.
*
* MT safe.
*/
void
gst_bus_set_flushing (GstBus * bus, gboolean flushing)
@ -507,10 +501,10 @@ gst_bus_set_flushing (GstBus * bus, gboolean flushing)
/**
* gst_bus_timed_pop_filtered:
* @bus: a #GstBus to pop from
* @timeout: a timeout in nanoseconds, or GST_CLOCK_TIME_NONE to wait forever
* @types: message types to take into account, GST_MESSAGE_ANY for any type
* @timeout: a timeout in nanoseconds, or %GST_CLOCK_TIME_NONE to wait forever
* @types: message types to take into account, %GST_MESSAGE_ANY for any type
*
* Get a message from the bus whose type matches the message type mask @types,
* Gets a message from the bus whose type matches the message type mask @types,
* waiting up to the specified timeout (and discarding any messages that do not
* match the mask provided).
*
@ -520,11 +514,7 @@ gst_bus_set_flushing (GstBus * bus, gboolean flushing)
*
* Returns: (transfer full) (nullable): a #GstMessage matching the
* filter in @types, or %NULL if no matching message was found on
* the bus until the timeout expired. The message is taken from
* the bus and needs to be unreffed with gst_message_unref() after
* usage.
*
* MT safe.
* the bus until the timeout expired.
*/
GstMessage *
gst_bus_timed_pop_filtered (GstBus * bus, GstClockTime timeout,
@ -630,7 +620,7 @@ beach:
* @bus: a #GstBus to pop
* @timeout: a timeout
*
* Get a message from the bus, waiting up to the specified timeout.
* Gets a message from the bus, waiting up to the specified timeout.
*
* If @timeout is 0, this function behaves like gst_bus_pop(). If @timeout is
* #GST_CLOCK_TIME_NONE, this function will block forever until a message was
@ -638,10 +628,7 @@ beach:
*
* Returns: (transfer full) (nullable): the #GstMessage that is on the
* bus after the specified timeout or %NULL if the bus is empty
* after the timeout expired. The message is taken from the bus
* and needs to be unreffed with gst_message_unref() after usage.
*
* MT safe.
* after the timeout expired.
*/
GstMessage *
gst_bus_timed_pop (GstBus * bus, GstClockTime timeout)
@ -656,7 +643,7 @@ gst_bus_timed_pop (GstBus * bus, GstClockTime timeout)
* @bus: a #GstBus to pop
* @types: message types to take into account
*
* Get a message matching @type from the bus. Will discard all messages on
* Gets a message matching @type from the bus. Will discard all messages on
* the bus that do not match @type and that have been posted before the first
* message that does match @type. If there is no message matching @type on
* the bus, all messages will be discarded. It is not possible to use message
@ -664,10 +651,7 @@ gst_bus_timed_pop (GstBus * bus, GstClockTime timeout)
*
* Returns: (transfer full) (nullable): the next #GstMessage matching
* @type that is on the bus, or %NULL if the bus is empty or there
* is no message matching @type. The message is taken from the bus
* and needs to be unreffed with gst_message_unref() after usage.
*
* MT safe.
* is no message matching @type.
*/
GstMessage *
gst_bus_pop_filtered (GstBus * bus, GstMessageType types)
@ -682,14 +666,10 @@ gst_bus_pop_filtered (GstBus * bus, GstMessageType types)
* gst_bus_pop:
* @bus: a #GstBus to pop
*
* Get a message from the bus.
* Gets a message from the bus.
*
* Returns: (transfer full) (nullable): the #GstMessage that is on the
* bus, or %NULL if the bus is empty. The message is taken from
* the bus and needs to be unreffed with gst_message_unref() after
* usage.
*
* MT safe.
* bus, or %NULL if the bus is empty.
*/
GstMessage *
gst_bus_pop (GstBus * bus)
@ -703,14 +683,11 @@ gst_bus_pop (GstBus * bus)
* gst_bus_peek:
* @bus: a #GstBus
*
* Peek the message on the top of the bus' queue. The message will remain
* on the bus' message queue. A reference is returned, and needs to be unreffed
* by the caller.
* Peeks the message on the top of the bus' queue. The message will remain
* on the bus' message queue.
*
* Returns: (transfer full) (nullable): the #GstMessage that is on the
* bus, or %NULL if the bus is empty.
*
* MT safe.
*/
GstMessage *
gst_bus_peek (GstBus * bus)
@ -931,14 +908,14 @@ gst_bus_create_watch_unlocked (GstBus * bus)
* gst_bus_create_watch:
* @bus: a #GstBus to create the watch for
*
* Create watch for this bus. The GSource will be dispatched whenever
* Create watch for this bus. The #GSource will be dispatched whenever
* a message is on the bus. After the GSource is dispatched, the
* message is popped off the bus and unreffed.
*
* As with other watches, there can only be one watch on the bus, including
* any signal watch added with #gst_bus_add_signal_watch.
*
* Returns: (transfer full) (nullable): a #GSource that can be added to a mainloop.
* Returns: (transfer full) (nullable): a #GSource that can be added to a #GMainLoop.
*/
GSource *
gst_bus_create_watch (GstBus * bus)
@ -1011,7 +988,7 @@ gst_bus_add_watch_full_unlocked (GstBus * bus, gint priority,
* There can only be a single bus watch per bus, you must remove it before you
* can set a new one.
*
* The bus watch will only work if a GLib main loop is being run.
* The bus watch will only work if a #GMainLoop is being run.
*
* When @func is called, the message belongs to the caller; if you want to
* keep a copy of it, call gst_message_ref() before leaving @func.
@ -1023,8 +1000,6 @@ gst_bus_add_watch_full_unlocked (GstBus * bus, gint priority,
* The bus watch will take its own reference to the @bus, so it is safe to unref
* @bus using gst_object_unref() after setting the bus watch.
*
* MT safe.
*
* Returns: The event source id or 0 if @bus already got an event source.
*/
guint
@ -1049,7 +1024,7 @@ gst_bus_add_watch_full (GstBus * bus, gint priority,
* @user_data: user data passed to @func.
*
* Adds a bus watch to the default main context with the default priority
* (%G_PRIORITY_DEFAULT). It is also possible to use a non-default main
* ( %G_PRIORITY_DEFAULT ). It is also possible to use a non-default main
* context set up using g_main_context_push_thread_default() (before
* one had to create a bus watch source and attach it to the desired main
* context 'manually').
@ -1058,7 +1033,7 @@ gst_bus_add_watch_full (GstBus * bus, gint priority,
* There can only be a single bus watch per bus, you must remove it before you
* can set a new one.
*
* The bus watch will only work if a GLib main loop is being run.
* The bus watch will only work if a #GMainLoop is being run.
*
* The watch can be removed using gst_bus_remove_watch() or by returning %FALSE
* from @func. If the watch was added to the default main context it is also
@ -1067,8 +1042,6 @@ gst_bus_add_watch_full (GstBus * bus, gint priority,
* The bus watch will take its own reference to the @bus, so it is safe to unref
* @bus using gst_object_unref() after setting the bus watch.
*
* MT safe.
*
* Returns: The event source id or 0 if @bus already got an event source.
*/
guint
@ -1198,7 +1171,7 @@ poll_destroy_timeout (GstBusPollData * poll_data)
* @timeout: the poll timeout, as a #GstClockTime, or #GST_CLOCK_TIME_NONE to poll
* indefinitely.
*
* Poll the bus for messages. Will block while waiting for messages to come.
* Polls the bus for messages. Will block while waiting for messages to come.
* You can specify a maximum time to poll with the @timeout parameter. If
* @timeout is negative, this function will block indefinitely.
*
@ -1212,7 +1185,7 @@ poll_destroy_timeout (GstBusPollData * poll_data)
* signal handler will see the same messages that this function sees -- neither
* will steal messages from the other.
*
* This function will run a main loop from the default main context when
* This function will run a #GMainLoop from the default main context when
* polling.
*
* You should never use this function, since it is pure evil. This is
@ -1233,9 +1206,7 @@ poll_destroy_timeout (GstBusPollData * poll_data)
* from there.
*
* Returns: (transfer full) (nullable): the message that was received,
* or %NULL if the poll timed out. The message is taken from the
* bus and needs to be unreffed with gst_message_unref() after
* usage.
* or %NULL if the poll timed out.
*/
GstMessage *
gst_bus_poll (GstBus * bus, GstMessageType events, GstClockTime timeout)
@ -1318,10 +1289,10 @@ gst_bus_async_signal_func (GstBus * bus, GstMessage * message, gpointer data)
* @message: the #GstMessage received
* @data: user data
*
* A helper GstBusSyncHandler that can be used to convert all synchronous
* A helper #GstBusSyncHandler that can be used to convert all synchronous
* messages into signals.
*
* Returns: GST_BUS_PASS
* Returns: %GST_BUS_PASS
*/
GstBusSyncReply
gst_bus_sync_signal_handler (GstBus * bus, GstMessage * message, gpointer data)
@ -1356,9 +1327,7 @@ gst_bus_sync_signal_handler (GstBus * bus, GstMessage * message, gpointer data)
* signals when messages arrive; gst_bus_add_signal_watch() adds an idle callback
* to pop messages off the bus *asynchronously*. The sync-message signal
* comes from the thread of whatever object posted the message; the "message"
* signal is marshalled to the main thread via the main loop.
*
* MT safe.
* signal is marshalled to the main thread via the #GMainLoop.
*/
void
gst_bus_enable_sync_message_emission (GstBus * bus)
@ -1384,8 +1353,6 @@ gst_bus_enable_sync_message_emission (GstBus * bus)
* "cancelled" by calling this function. In this way the semantics are exactly
* the same as gst_object_ref() that which calls enable should also call
* disable.
*
* MT safe.
*/
void
gst_bus_disable_sync_message_emission (GstBus * bus)
@ -1410,7 +1377,7 @@ gst_bus_disable_sync_message_emission (GstBus * bus)
* main context 'manually').
*
* After calling this statement, the bus will emit the "message" signal for each
* message posted on the bus when the main loop is running.
* message posted on the bus when the #GMainLoop is running.
*
* This function may be called multiple times. To clean up, the caller is
* responsible for calling gst_bus_remove_signal_watch() as many times as this
@ -1418,8 +1385,6 @@ gst_bus_disable_sync_message_emission (GstBus * bus)
*
* There can only be a single bus watch per bus, you must remove any signal
* watch before you can set another type of watch.
*
* MT safe.
*/
void
gst_bus_add_signal_watch_full (GstBus * bus, gint priority)
@ -1468,7 +1433,7 @@ has_gsource:
* @bus: a #GstBus on which you want to receive the "message" signal
*
* Adds a bus signal watch to the default main context with the default priority
* (%G_PRIORITY_DEFAULT). It is also possible to use a non-default
* ( %G_PRIORITY_DEFAULT ). It is also possible to use a non-default
* main context set up using g_main_context_push_thread_default() (before
* one had to create a bus watch source and attach it to the desired main
* context 'manually').
@ -1479,8 +1444,6 @@ has_gsource:
* This function may be called multiple times. To clean up, the caller is
* responsible for calling gst_bus_remove_signal_watch() as many times as this
* function is called.
*
* MT safe.
*/
void
gst_bus_add_signal_watch (GstBus * bus)
@ -1493,8 +1456,6 @@ gst_bus_add_signal_watch (GstBus * bus)
* @bus: a #GstBus you previously added a signal watch to
*
* Removes a signal watch previously added with gst_bus_add_signal_watch().
*
* MT safe.
*/
void
gst_bus_remove_signal_watch (GstBus * bus)

29
gst/gstbus.h
View file

@ -78,7 +78,7 @@ typedef enum
* into the bus. This function is mostly used internally. Only one sync handler
* can be attached to a given bus.
*
* If the handler returns GST_BUS_DROP, it should unref the message, else the
* If the handler returns %GST_BUS_DROP, it should unref the message, else the
* message should not be unreffed by the sync handler.
*
* Returns: #GstBusSyncReply stating what to do with the message
@ -98,8 +98,8 @@ typedef GstBusSyncReply (*GstBusSyncHandler) (GstBus * bus, GstMessage * mess
* The message passed to the function will be unreffed after execution of this
* function so it should not be freed in the function.
*
* Note that this function is used as a GSourceFunc which means that returning
* %FALSE will remove the GSource from the mainloop.
* Note that this function is used as a #GSourceFunc which means that returning
* %FALSE will remove the #GSource from the mainloop.
*
* Returns: %FALSE if the event source should be removed.
*/
@ -107,6 +107,7 @@ typedef gboolean (*GstBusFunc) (GstBus * bus, GstMessage * mess
/**
* GstBus:
* @object: the parent structure
*
* The opaque #GstBus data structure.
*/
@ -120,12 +121,34 @@ struct _GstBus
gpointer _gst_reserved[GST_PADDING];
};
/**
* GstBusClass:
* @parent_class: the parent class structure
*
* GStreamer bus class.
*/
struct _GstBusClass
{
GstObjectClass parent_class;
/* signals */
/**
* GstBusClass::message:
* @bus: the #GstBus
* @message: the message that has been posted asynchronously
*
* A message has been posted on the bus.
*/
void (*message) (GstBus *bus, GstMessage *message);
/**
* GstBusClass::sync_message:
* @bus: the #GstBus
* @message: the message that has been posted synchronously
*
* A message has been posted on the bus.
*/
void (*sync_message) (GstBus *bus, GstMessage *message);
/*< private >*/