|
Media.Streaming.GStreamer.Core.Bus |
|
|
|
|
|
Synopsis |
|
|
|
|
Detail
|
|
The Bus is resposible for delivering Messages in a
first-in, first-out order, from the streaming threads to the
application.
Since the application typically only wants to deal with
delivery of these messages from one thread, the Bus will
marshal the messages between different threads. This is
important since the actual streaming of media is done in
a thread separate from the application.
The Bus provides support for Source
based notifications. This makes it possible to handle the
delivery in the GLib Source.
A message is posted on the bus with the busPost method. With
the busPeek and busPop methods one can look at or retrieve
a previously posted message.
The bus can be polled with the busPoll 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 busAddWatch. This function
will install a 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 busSetSyncHandler 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 Pipeline has one bus.
Note that a Pipeline will set its bus into flushing state
when changing from StateReady to StateNull.
|
|
Types
|
|
data Bus |
Instances | |
|
|
class ObjectClass o => BusClass o |
| Instances | |
|
|
The result of a BusSyncHandler.
|
|
data BusSyncReply |
Instances | |
|
|
A handler that will be invoked synchronously when a new message
is injected into the bus. This function is mostly used internally.
Only one sync handler may be attached to a given bus.
|
|
type BusSyncHandler = Bus -> Message -> IO BusSyncReply |
|
castToBus :: GObjectClass obj => obj -> Bus |
|
toBus :: BusClass o => o -> Bus |
|
Bus Operations
|
|
busGetFlags |
:: BusClass busT | | => busT | bus - a Bus
| -> IO [BusFlags] | the flags set on bus
| Get the flags set on this bus.
|
|
|
busSetFlags |
:: BusClass busT | | => busT | bus - a Bus
| -> [BusFlags] | the flags to set on bus
| -> IO () | | Set flags on this bus.
|
|
|
busUnsetFlags |
:: BusClass busT | | => busT | bus - a Bus
| -> [BusFlags] | the flags to unset on bus
| -> IO () | | Unset flags on this bus.
|
|
|
busNew |
:: IO Bus | the newly created Bus object
| Create a new bus.
|
|
|
busPost |
:: BusClass busT | | => busT | bus - a Bus
| -> Message | message - the message to post
| -> IO Bool | True if the message was posted, or
False if the bus is flushing
| Post a message to the bus.
|
|
|
busHavePending |
:: BusClass busT | | => busT | bus - a Bus
| -> IO Bool | True if there are messages
on the bus to be handled, otherwise False
| Check if there are pending messages on the bus.
|
|
|
busPeek |
:: BusClass busT | | => busT | bus - a Bus
| -> IO (Maybe Message) | the first Message on the bus, or
Nothing if the bus is empty
| Get the message at the front of the queue. Any message returned
will remain on the queue.
|
|
|
busPop |
:: BusClass busT | | => busT | bus - a Bus
| -> IO (Maybe Message) | the first Message on the bus, or
Nothing if the bus is empty
| Get the message at the front of the queue. It will be removed
from the queue.
|
|
|
busTimedPop |
:: BusClass busT | | => busT | bus - a Bus
| -> Maybe ClockTime | timeoutM - the time to wait for,
or Nothing to wait forever
| -> IO (Maybe Message) | the first message recieved, or
Nothing if the timeout has expired
| Get a message from the bus, waiting up to the specified timeout.
If the time given is Nothing, the function will wait forever.
If the time given is 0, the function will behave like busPop.
Since 0.10.12.
|
|
|
busSetFlushing |
:: BusClass busT | | => busT | bus - a Bus
| -> Bool | flushing - the new flushing state
| -> IO () | | If flushing is True, the bus will flush out any queued
messages, as well as any future messages, until the function is
called with flushing set to False.
|
|
|
busSetSyncHandler |
:: BusClass busT | | => busT | bus - a Bus
| -> Maybe BusSyncHandler | busSyncHandlerM - the new BusSyncHandler
| -> IO () | | Set the synchronous message handler on the bus. The function will
be called every time a new message is posted to the bus. Note
that the function will be called from the thread context of the
poster.
Calling this function will replace any previously set sync
handler. If Nothing is passed to this function, it will unset
the handler.
|
|
|
busUseSyncSignalHandler |
:: BusClass busT | | => busT | bus - a Bus
| -> IO () | | Use a synchronous message handler that converts all messages to signals.
|
|
|
busCreateWatch |
:: BusClass busT | | => busT | bus - a Bus
| -> IO Source | the new event Source
| Create a watch for the bus. The Source will dispatch a signal
whenever a message is on the bus. After the signal is dispatched,
the message is popped off the bus.
|
|
|
busAddWatch |
:: BusClass busT | | => busT | bus - a Bus
| -> Priority | priority - the priority of the watch
| -> BusFunc | func - the action to perform when a message is recieved
| -> IO HandlerId | the event source ID
| 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.
The watch can be removed by calling sourceRemove.
|
|
|
busDisableSyncMessageEmission |
|
|
busEnableSyncMessageEmission |
:: BusClass busT | | => busT | bus - a Bus
| -> IO () | | Instructs GStreamer to emit the busSyncMessage signal after
running the bus's sync handler. This function is here so that
programmers can ensure that they can synchronously receive
messages without having to affect what the bin's sync handler is.
This function may be called multiple times. To clean up, the
caller is responsible for calling busDisableSyncMessageEmission
as many times as this function is called.
While this function looks similar to busAddSignalWatch, it is
not exactly the same -- this function enables synchronous
emission of signals when messages arrive; busAddSignalWatch
adds an idle callback to pop messages off the bus
asynchronously. The busSyncMessage signal comes from the thread
of whatever object posted the message; the busMessage signal is
marshalled to the main thread via the main loop.
|
|
|
busAddSignalWatch |
:: BusClass busT | | => busT | bus - a Bus
| -> Priority | priority - the priority of the watch
| -> IO () | | Adds a bus signal watch to the default main context with the
given priority. After calling this method, the bus will emit the
busMessage signal for each message posted on the bus.
This function may be called multiple times. To clean up, the
caller is responsible for calling busRemoveSignalWatch as many
times.
|
|
|
busRemoveSignalWatch |
|
|
busPoll |
:: BusClass busT | | => busT | bus - a Bus
| -> [MessageType] | events - the set of messages to poll for
| -> ClockTimeDiff | timeout - the time to wait, or -1 to wait indefinitely
| -> IO Message | | Poll the bus for a message. Will block while waiting for messages
to come. You can specify the maximum amount of time to wait with
the timeout parameter. If timeout is negative, the function
will wait indefinitely.
Messages not in events will be popped off the bus and ignored.
Because busPoll is implemented using the busMessage signal
enabled by busAddSignalWatch, calling busPoll will cause the
busMessage signal to be emitted for every message that the
function sees. Thus, a busMessage signal handler will see every
message that busPoll sees -- neither will steal messages from
the other.
This function will run a main loop in the default main context
while polling.
|
|
|
Bus Signals
|
|
busMessage :: BusClass busT => Signal busT (Message -> IO ()) |
A message has been posted on the bus. This signal is emitted from
a Source added to the MainLoop, and only when it is running.
|
|
busSyncMessage :: BusClass busT => Signal busT (Message -> IO ()) |
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 must first call
busUseSyncSignalHandler if you want this signal to be emitted
when a message is posted on the bus.
|
|
Produced by Haddock version 0.8 |