* 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.
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.
*
/**
* 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
/**
* 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),
* @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)
* 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)
* @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)
/**
* 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).
*
*
* 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,
* @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
*
* 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)
* @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
*
* 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)
* 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)
* 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)
* 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)
* 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.
* 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
* @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').
* 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
* 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
* @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.
*
* 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
* 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)
* @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)
* 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)
* "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)
* 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
*
* 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)
* @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').
* 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)
* @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)