3.4 bus%
On this page:
post
have-pending?
peek
pop
pop-filtered
timed-pop
timed-pop-filtered
disable-sync-message-emission!
enable-sync-message-emission!
poll
make-bus-channel
3.4.1 Messages
message?
message-type
message-seqnum
message-src
message-of-type?
eos-message?
error-message?
fatal-message?
message-type/  c
Inherited methods:
from gst-object%
get-name
get-parent
get-path-string
has-as-parent?
7.7

class

bus% : class?

  superclass: gst-object%

The bus is responsible for delivering messages in a first-in first-out way from a pipeline.

method

(send a-bus post message)  boolean?

  message : message?
Post the message on a-bus. Returns #t if the message could be posted, otherwise #f.

method

(send a-bus have-pending?)  boolean?

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

method

(send a-bus peek)  (or/c message? #f)

Peek the message on the top of a-bus’ queue. The message will remain on the queue. Returns #f if the bus is empty.

method

(send a-bus pop)  (or/c message? #f)

Gets a message from a-bus, or #f if the bus is empty.

method

(send a-bus pop-filtered types)  (or/c message? #f)

  types : message-type/c
Get a message matching any of the given types from a-bus. Will discard all messages on the bus that do not match types. Retruns #f if the bus is empty or there are no messages that match types.

method

(send a-bus timed-pop timeout)  (or/c message? #f)

  timeout : clock-time?
Gets a message from a-bus, waiting up to the specified timeout. If timeout is clock-time-none, this method will block until a message was posted on the bus. Returns #f if the bus is empty after the timeout expired.

method

(send a-bus timed-pop-filtered timeout    
  types)  (or/c message? #f)
  timeout : clock-time?
  types : message-type/c
Gets a message from a-bus whose type matches one of the message types in types, waiting up to the specified timeout and discarding any messages that do not match the mask provided.

If timeout is 0, this method behaves like pop-filtered. If timeout is clock-time-none, this method will block until a matching message was posted on the bus. Returns #f if no matching message was found on the bus after the timeout expired.

Instructs GStreamer to stop emitting the 'sync-message signal for a-bus. See enable-sync-message-emission! for more information.

Instructs GStreamer to emit the 'sync-message signal after running a-bus’s sync handler. Use connect on a-bus to listen for this signal.

method

(send a-bus poll events timeout)  (or/c message? #f)

  events : message-type/c
  timeout : clock-time?
Poll a-bus for messages. Will block while waiting for messages to come. Specify a maximum time to poll with timeout. If timeout is negative, this method will block indefinitely.

GStreamer calls this function “pure evil”. Prefer timed-pop-filtered and make-bus-channel.

procedure

(make-bus-channel bus 
  [filter 
  #:timeout timeout]) 
  (evt/c (or/c message? false/c (evt/c exact-integer?)))
  bus : (is-a?/c bus%)
  filter : message-type/c = '(any)
  timeout : clock-time? = clock-time-none
This procedure polls bus asynchronously using timed-pop-filtered (the filter and timeout arguments are forwarded on to that method) and returns a synchronizable event.

That event is ready for synchronization when a new message is emitted from the bus (in which case the synchronization result is a message), when the timeout has been reached (in which case the synchronization result will be a message or #f), or when the bus has flushed and closed down (in which case the synchronization result is another event that is always ready for synchronization).

3.4.1 Messages

A message is a small structure representing signals emitted from a pipeline and passed to the application using the bus. Messages have a message-type useful for taking different actions depending on the type.

procedure

(message? v)  boolean?

  v : any/c
Returns #t if v is a message emitted from a bus, #f otherwise.

procedure

(message-type message)  message-type/c

  message : message?
Gets the type of message.

procedure

(message-seqnum message)  exact-integer?

  message : message?
Retrieve the sequence number of message.

Messages have ever-incrementing sequence numbers. Sequence numbers are typically used to indicate that a message corresponds to some other set of messages or events.

procedure

(message-src message)  (is-a?/c gst-object%)

  message : message?
Get the object that posted message.

procedure

(message-of-type? message type ...+)  (or/c message-type/c #f)

  message : message?
  type : symbol?
Checks if the type of message is one of the given types. Returns #f if the message-type of message is not one of the given types.

procedure

(eos-message? v)  boolean?

  v : any/c
Returns #t if v is a message? and has the message-type of 'eos, otherwise #f.

procedure

(error-message? v)  boolean?

  v : any/c
Returns #t if v is a message? and has the message-type of 'error, otherwise #f.

procedure

(fatal-message? v)  boolean?

  v : any/c
 = (or (eos-message? v) (error-message? v))
Returns #t if v is a message? and has a message-type indicating that the pipeline that emitted this message should shut down (either a 'eos or 'error message), otherwise #f.

A contract matching a list of allowed message types.