Next: , Previous: GstBuffer, Up: Top

4 GstBus

Asynchronous message bus subsystem

4.1 Overview

The <gst-bus> is an object responsible for delivering <gst-messages> in a first-in first-out way from the streaming threads to the application.

Since the application typically only wants to deal with delivery of these messages from one thread, the GstBus will marshall the messages between different threads. This is important since the actual streaming of media is done in another thread than the application.

The GstBus provides support for <g-source> based notifications. This makes it possible to handle the delivery in the glib mainloop.

The <g-source> callback function gst-bus-async-signal-func can be used to convert all bus messages into signal emissions.

A message is posted on the bus with the gst-bus-post method. With the gst-bus-peek and gst-bus-pop methods one can look at or retrieve a previously posted message.

The bus can be polled with the gst-bus-poll method. This methods blocks up to the specified timeout value until one of the specified messages types is posted on the bus. The application can then -pop the messages from the bus to handle them. Alternatively the application can register an asynchronous bus function using gst-bus-add-watch-full or gst-bus-add-watch. This function will install a <g-source> in the default glib main loop and will deliver messages a short while after they have been posted. Note that the main loop should be running for the asynchronous callbacks.

It is also possible to get messages from the bus without any thread marshalling with the gst-bus-set-sync-handler method. This makes it possible to react to a message in the same thread that posted the message on the bus. This should only be used if the application is able to deal with messages from different threads.

Every <gst-pipeline> has one bus.

Note that a <gst-pipeline> will set its bus into flushing state when changing from READY to NULL state.

Last reviewed on 2006-03-12 (0.10.5)

4.2 Usage

— Class: <gst-bus>

This <gobject> class defines no properties, other than those defined by its superclasses.

— Signal on <gst-bus>: sync-message (arg0 <gst-message>)

A message has been posted on the bus. This signal is emitted from the thread that posted the message so one has to be careful with locking.

This signal will not be emitted by default, you have to set up gst-bus-sync-signal-handler as a sync handler if you want this signal to be emitted when a message is posted on the bus, like this: 

          
          gst_bus_set_sync_handler (bus, gst_bus_sync_signal_handler, yourdata);
— Signal on <gst-bus>: message (arg0 <gst-message>)

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.

— Function: gst-bus-new   (ret <gst-bus>)

Creates a new <gst-bus> instance.

ret
a new <gst-bus> instance
— Function: gst-bus-post (self <gst-bus>) (message <gst-message>)   (ret bool)
— Method: post

Post a message on the given bus. Ownership of the message is taken by the bus.

bus
a <gst-bus> to post on
message
The <gst-message> to post
ret
TRUE if the message could be posted, FALSE if the bus is flushing. MT safe.
— Function: gst-bus-have-pending (self <gst-bus>)   (ret bool)
— Method: have-pending

Check if there are pending messages on the bus that should be handled.

bus
a <gst-bus> to check
ret
TRUE if there are messages on the bus to be handled, FALSE otherwise. MT safe.
— Function: gst-bus-peek (self <gst-bus>)   (ret <gst-message>)
— Method: peek

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.

bus
a <gst-bus>
ret
The <gst-message> that is on the bus, or NULL if the bus is empty. MT safe.
— Function: gst-bus-pop (self <gst-bus>)   (ret <gst-message>)
— Method: pop

Get a message from the bus.

bus
a <gst-bus> to pop
ret
The <gst-message> 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.
— Function: gst-bus-set-flushing (self <gst-bus>) (flushing bool)
— Method: set-flushing

If flushing, flush out and unref 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 #f.

MT safe.

bus
a <gst-bus>
flushing
whether or not to flush the bus
— Function: gst-bus-set-sync-handler (self <gst-bus>) (func <gst-bus-sync-handler>) (data <gpointer>)
— Method: set-sync-handler

Sets the synchronous handler on the bus. The function will be called every time a new message is posted on the bus. Note that the function will be called in the same thread context as the posting object. This function is usually only called by the creator of the bus. Applications should handle messages asynchronously using the gst_bus watch and poll functions.

You cannot replace an existing sync_handler. You can pass NULL to this function, which will clear the existing handler.

bus
a <gst-bus> to install the handler on
func
The handler function to install
data
User data that will be sent to the handler function.
— Function: gst-bus-sync-signal-handler (self <gst-bus>) (message <gst-message>) (data <gpointer>)   (ret <gst-bus-sync-reply>)
— Method: sync-signal-handler

A helper GstBusSyncHandler that can be used to convert all synchronous messages into signals.

bus
a <gst-bus>
message
the <gst-message> received
data
user data
ret
GST_BUS_PASS
— Function: gst-bus-create-watch (self <gst-bus>)   (ret <g-source*>)
— Method: create-watch

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.

bus
a <gst-bus> to create the watch for
ret
A <g-source> that can be added to a mainloop.
— Function: gst-bus-add-watch-full (self <gst-bus>) (priority int) (func <gst-bus-func>) (user_data <gpointer>) (notify <g-destroy-notify>)   (ret unsigned-int)
— Method: add-watch-full

Adds a bus watch to the default main context with the given priority. This function is used to receive asynchronous messages in the main loop.

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 watch can be removed using g-source-remove or by returning FALSE from func.

bus
a <gst-bus> to create the watch for.
priority
The priority of the watch.
func
A function to call when a message is received.
user-data
user data passed to func.
notify
the function to call when the source is removed.
ret
The event source id. MT safe.
— Function: gst-bus-add-watch (self <gst-bus>) (func <gst-bus-func>) (user_data <gpointer>)   (ret unsigned-int)
— Method: add-watch

Adds a bus watch to the default main context with the default priority. This function is used to receive asynchronous messages in the main loop.

The watch can be removed using g-source-remove or by returning FALSE from func.

bus
a <gst-bus> to create the watch for
func
A function to call when a message is received.
user-data
user data passed to func.
ret
The event source id. MT safe.
— Function: gst-bus-async-signal-func (self <gst-bus>) (message <gst-message>) (data <gpointer>)   (ret bool)
— Method: async-signal-func

A helper <gst-bus-func> that can be used to convert all asynchronous messages into signals.

bus
a <gst-bus>
message
the <gst-message> received
data
user data
ret
TRUE
— Function: gst-bus-add-signal-watch (self <gst-bus>)
— Method: add-signal-watch

Adds a bus signal watch to the default main context with the default priority. After calling this statement, the bus will emit the "message" signal for each message posted on the bus.

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.

bus
a <gst-bus> on which you want to receive the "message" signal
— Function: gst-bus-add-signal-watch-full (self <gst-bus>) (priority int)
— Method: add-signal-watch-full

Adds a bus signal watch to the default main context with the given priority. After calling this statement, the bus will emit the "message" signal for each message posted on the bus when the main loop 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 function is called.

MT safe.

bus
a <gst-bus> on which you want to receive the "message" signal
priority
The priority of the watch.
— Function: gst-bus-remove-signal-watch (self <gst-bus>)
— Method: remove-signal-watch

Removes a signal watch previously added with gst-bus-add-signal-watch.

MT safe.

bus
a <gst-bus> you previously added a signal watch to
— Function: gst-bus-poll (self <gst-bus>) (events <gst-message-type>) (timeout unsigned-long-long)   (ret <gst-message>)
— Method: poll

Poll 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.

All messages not in events will be popped off the bus and will be ignored.

Because poll is implemented using the "message" signal enabled by gst-bus-add-signal-watch, calling gst-bus-poll will cause the "message" signal to be emitted for every message that poll sees. Thus a "message" 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 polling.

bus
a <gst-bus>
events
a mask of <gst-message-type>, representing the set of message types to poll for.
timeout
the poll timeout, as a <gst-clock-time-diff>, or -1 to poll indefinitely.
ret
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.