Class: Gst::Bus

Inherits:
Object
  • Object
show all
Defined in:
lib/gst/bus.rb

Overview

GStreamer bus class.

Instance Method Summary collapse

Methods inherited from Object

#add_control_binding, check_uniqueness, #control_bindings_disabled=, #control_rate, #control_rate=, default_deep_notify, #default_error, #get_control_binding, #get_g_value_array, #get_value, #get_value_array, #has_active_control_bindings, #has_ancestor, #has_as_ancestor, #has_as_parent, #name, #name=, #parent, #parent=, #path_string, #ref, ref_sink, #remove_control_binding, replace, #set_control_binding_disabled, #suggest_next_sync, #sync_values, #unparent, #unref

Constructor Details

#initialize ⇒ Gst::Bus

Creates a new Gst::Bus instance.

Instance Method Details

#add_signal_watch ⇒ nil

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 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').

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.

Returns:

  • (nil)

#add_signal_watch_full(priority) ⇒ nil

Adds a bus signal watch to the default main context with the given priority (e.g. %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').

After calling this statement, the bus will emit the "message" signal for each message posted on the bus when the GMain::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.

There can only be a single bus watch per bus, you must remove any signal watch before you can set another type of watch.

Parameters:

  • priority (Integer) —

    The priority of the watch.

Returns:

  • (nil)

#add_watch(priority = GLib::PRIORITY_DEFAULT, &block) ⇒ Integer

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 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 is used to receive asynchronous messages in the main loop. 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 GMain::Loop 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 possible to remove the watch using g_source_remove().

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.

Parameters:

  • func (Gst::BusFunc) —

    A function to call when a message is received.

  • user_data (GObject) —

    user data passed to func.

Returns:

  • (Integer) —

    The event source id or 0 if bus already got an event source.



20
21
22
 
# File 'lib/gst/bus.rb', line 20

def add_watch(priority=GLib::PRIORITY_DEFAULT, &block)
  add_watch_full(priority, &block)
end

#add_watch_full(priority, func, user_data, notify) ⇒ Integer

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 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 is used to receive asynchronous messages in the main loop. 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 GMain::Loop 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 possible to remove the watch using g_source_remove().

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.

Parameters:

  • func (Gst::BusFunc) —

    A function to call when a message is received.

  • user_data (GObject) —

    user data passed to func.

Returns:

  • (Integer) —

    The event source id or 0 if bus already got an event source.




# File 'lib/gst/bus.rb', line 19

#async_signal_func(message, data) ⇒ Boolean

A helper Gst::BusFunc that can be used to convert all asynchronous messages into signals.

Parameters:

  • message (Gst::Message) —

    the Gst::Message received

  • data (GObject) —

    user data

Returns:

  • (Boolean) —

    true

#create_watch ⇒ GLib::Source

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:

  • (GLib::Source) —

    a #GSource that can be added to a GMain::Loop.

#disable_sync_message_emission ⇒ nil

Instructs GStreamer to stop emitting the "sync-message" signal for this bus. See gst_bus_enable_sync_message_emission() for more information.

In the event that multiple pieces of code have called gst_bus_enable_sync_message_emission(), the sync-message emissions will only be stopped after all calls to gst_bus_enable_sync_message_emission() were "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.

Returns:

  • (nil)

#enable_async=(enable_async) ⇒ Boolean

Enables async message delivery support for bus watches, gst_bus_pop() and similar API. Without this only the synchronous message handlers are called.

This property is used to create the child element buses in Gst::Bin.

Parameters:

  • enable_async (Boolean)

Returns:

  • (Boolean) —

    enable-async

#enable_sync_message_emission ⇒ nil

Instructs GStreamer to emit the "sync-message" signal after running the bus's sync handler. This function is here so that code 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 gst_bus_disable_sync_message_emission() as many times as this function is called.

While this function looks similar to gst_bus_add_signal_watch(), it is not exactly the same -- this function enables synchronous emission of 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 GMain::Loop.

Returns:

  • (nil)

#flushing=(flushing) ⇒ nil

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.

Parameters:

  • flushing (Boolean) —

    whether or not to flush the bus

Returns:

  • (nil)

#get_pollfd(fd) ⇒ nil

Gets the file descriptor from the bus which can be used to get notified about messages being available with functions like g_poll(), and allows integration into other event loops based on file descriptors. Whenever a message is available, the POLLIN / %G_IO_IN event is set.

Warning: NEVER read or write anything to the returned fd but only use it for getting notifications via g_poll() or similar and then use the normal GstBus API, e.g. gst_bus_pop().

Parameters:

  • fd (GLib::PollFD) —

    A GPollFD to fill

Returns:

  • (nil)

#have_pending ⇒ Boolean

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

Returns:

  • (Boolean) —

    true if there are messages on the bus to be handled, false

#peek ⇒ Gst::Message

Peeks the message on the top of the bus' queue. The message will remain on the bus' message queue.

Returns:

  • (Gst::Message) —

    the Gst::Message that is on the bus, or nil if the bus is empty.

#poll(*args) ⇒ Gst::Message

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.

All messages not in events will be popped off the bus and will be ignored. It is not possible to use message enums beyond #GST_MESSAGE_EXTENDED in the events mask

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 GMain::Loop from the default main context when polling.

You should never use this function, since it is pure evil. This is especially true for GUI applications based on Gtk+ or Qt, but also for any other non-trivial application that uses the GLib main loop. As this function runs a GLib main loop, any callback attached to the default GLib main context may be invoked. This could be timeouts, GUI events, I/O events etc.; even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks may do things you do not expect, e.g. destroy the main application window or some other resource; change other application state; display a dialog and run another main loop until the user clicks it away. In short, using this function may add a lot of complexity to your code through unexpected re-entrancy and unexpected changes to your application's state.

For 0 timeouts use gst_bus_pop_filtered() instead of this function; for other short timeouts use gst_bus_timed_pop_filtered(); everything else is better handled by setting up an asynchronous bus watch and doing things from there. poll for (note special handling of extended message types below) indefinitely.

Parameters:

  • events (Gst::MessageType) —

    a mask of Gst::MessageType, representing the set of message types to

  • timeout (Gst::ClockTime) —

    the poll timeout, as a Gst::ClockTime, or #GST_CLOCK_TIME_NONE to poll

Returns:

  • (Gst::Message) —

    the message that was received, or nil if the poll timed out.



41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/gst/bus.rb', line 41

def poll(*args)
  events = nil
  timeout = nil

  n_args = args.size
  case n_args
  when 0
  when 1
    case args[0]
    when Hash
      options = args[0]
      events = options[:events]
      timeout = options[:timeout]
    when Integer
      timeout = args[0]
    else
      events = args[0]
    end
  when 2
    events, timeout = args
  else
    message = "wrong number of arguments "
    message << "(given #{n_args}, expected 0..2)"
    raise ArgumentError, message
  end
  poll_raw(events || :any,
           timeout || CLOCK_TIME_NONE)
end

#poll_raw ⇒ Gst::Message

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.

All messages not in events will be popped off the bus and will be ignored. It is not possible to use message enums beyond #GST_MESSAGE_EXTENDED in the events mask

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 GMain::Loop from the default main context when polling.

You should never use this function, since it is pure evil. This is especially true for GUI applications based on Gtk+ or Qt, but also for any other non-trivial application that uses the GLib main loop. As this function runs a GLib main loop, any callback attached to the default GLib main context may be invoked. This could be timeouts, GUI events, I/O events etc.; even if gst_bus_poll() is called with a 0 timeout. Any of these callbacks may do things you do not expect, e.g. destroy the main application window or some other resource; change other application state; display a dialog and run another main loop until the user clicks it away. In short, using this function may add a lot of complexity to your code through unexpected re-entrancy and unexpected changes to your application's state.

For 0 timeouts use gst_bus_pop_filtered() instead of this function; for other short timeouts use gst_bus_timed_pop_filtered(); everything else is better handled by setting up an asynchronous bus watch and doing things from there. poll for (note special handling of extended message types below) indefinitely.

Parameters:

  • events (Gst::MessageType) —

    a mask of Gst::MessageType, representing the set of message types to

  • timeout (Gst::ClockTime) —

    the poll timeout, as a Gst::ClockTime, or #GST_CLOCK_TIME_NONE to poll

Returns:

  • (Gst::Message) —

    the message that was received, or nil if the poll timed out.




# File 'lib/gst/bus.rb', line 40

#pop ⇒ Gst::Message

Gets a message from the bus.

Returns:

  • (Gst::Message) —

    the Gst::Message that is on the bus, or nil if the bus is empty.

#pop_filtered(types) ⇒ Gst::Message

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 enums beyond #GST_MESSAGE_EXTENDED in the events mask.

Parameters:

Returns:

  • (Gst::Message) —

    the next Gst::Message matching type that is on the bus, or nil if the bus is empty or there is no message matching type.

#post(message) ⇒ Boolean

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

Parameters:

  • message (Gst::Message) —

    the Gst::Message to post

Returns:

  • (Boolean) —

    true if the message could be posted, false if the bus is flushing.

#remove_signal_watch ⇒ nil

Removes a signal watch previously added with gst_bus_add_signal_watch().

Returns:

  • (nil)

#remove_watch ⇒ Boolean

Removes an installed bus watch from bus.

Returns:

  • (Boolean) —

    true on success or false if bus has no event source.

#sync_handler(&block) ⇒ Object 



24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/gst/bus.rb', line 24

def sync_handler(&block)
  @sync_handler = lambda do |bus, message|
    begin
      block.call(bus, message)
    rescue Exception
      $stderr.puts("An exception is raised in " +
                     "#{self.class}\##{__method__} callback: #{block}")
      $stderr.puts("#{$!.class}: #{$!.message}")
      $stderr.puts($@)
      BusSyncReply::DROP
    end
  end
  set_sync_handler(&@sync_handler)
end

#sync_signal_handler(message, data) ⇒ Gst::BusSyncReply

A helper Gst::BusSyncHandler that can be used to convert all synchronous messages into signals.

Parameters:

  • message (Gst::Message) —

    the Gst::Message received

  • data (GObject) —

    user data

Returns:

#timed_pop(timeout) ⇒ Gst::Message

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 posted on the bus.

Parameters:

  • timeout (Gst::ClockTime) —

    a timeout

Returns:

  • (Gst::Message) —

    the Gst::Message that is on the bus after the specified timeout or nil if the bus is empty after the timeout expired.

#timed_pop_filtered(timeout, types) ⇒ Gst::Message

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

If timeout is 0, this function behaves like gst_bus_pop_filtered(). If timeout is #GST_CLOCK_TIME_NONE, this function will block forever until a matching message was posted on the bus.

Parameters:

  • timeout (Gst::ClockTime) —

    a timeout in nanoseconds, or %GST_CLOCK_TIME_NONE to wait forever

  • types (Gst::MessageType) —

    message types to take into account, %GST_MESSAGE_ANY for any type

Returns:

  • (Gst::Message) —

    a Gst::Message matching the filter in types, or nil if no matching message was found on the bus until the timeout expired.