docs/random/wtay/events

This is a round up from our IRC session on events. It's open for
discussion of course.

Definition 
----------

The event system is designed to be a mechanism for _inter_plugin_
communication. Their scope is therefore limited in a way that they do
not serve as a way to communicate between plugins and the app (signals
and properties are still used for plugin-app communication).

Events will be generated by either a plugin or the app. It should be
possible for a plugin to generate an event on one of its pads and it
should be possible for an app to insert an event on an arbitrary pad in
the pipeline.


Event handling 
--------------

Events can both travel upstream or downstream. Some events, by nature,
only travel in one direction.

* downstream events

  - Travel in the same way buffers do. This includes that they are handled
    by the scheduler. The rationale is that the events should be kept
    as close to the buffers are possible.

  - plugins should check the type of the GstData passed in the _chain
    or _loop function and act appropriatly. This can be done by either 
    doing their own stuff or by calling the default handler.

  - are handled on the sink pad.

* upstream events

  - are handled with an event handler attached to the srcpad. A default
    handler will be implemented for pads that don't implement their own 
    handler.

  - travel as fast as possible. the rationale is that a seek event should
    get to the src element ASAP.


Possible candidates for events 
------------------------------

  - QoS
   quality of service. Plugins can notify other plugins about the quality
   of the pipeline. A video element can for example say that it receives
   too much frames and that plugins connected to it need to slow down.

  - EOS
   A plugin can notify other plugins that it has run out-of-data.

  - Seek
   Used to notify plugins that they need to seek to a certain byte offset
   or timestamp.

  - discontinuous
   A plugin has detected a discontinuity in the stream. Other plugins
   might need to resync.

  - flush
   Plugins need to get rid of any buffered data ASAP.

  - caps nego??  
  - bufferpool get??  
  - ...


application generated events 
----------------------------

The application can insert events into the pipeline at arbirary
places. This will be done by calling gst_pad_event() on a pad.

A first implementation will only cover inserting events on src pads
since inserting events on sinkpads needs changes to the scheduler.


Effects of events on plugins 
----------------------------

some events are going to change the state of an element. The EOS event
will for example change the state of an element to the PAUSED state. Not
sure when or how this will happen.


use cases 
---------

1) filesrc ! fakesink

filesrc will read until it reaches EOF. It will then create a GstEvent
of type EOS and return it in the _get function. The event will travel
downstream and will reach the fakesink element. Fakesink will detect
the event in the _chain function and will call the default handler. The
default handler will set the element to the paused state. filesrc will
eventually change its state to PAUSED, probably before sending out the
event (TBD)

2) filesrc ! fakesink

The app wants to perform a seek on filesrc. It'll call the gst_pad_event()
on filesrcs src pad with the SEEK event type. The event handler will
react and change filesrcs internal status. filesrc will return a DISCONT
event before returning the buffer with the new offset.

3) filesrc ! mpeg2parse video_0! queue ! { mpeg2dec ! xvideosink }

lost of possibilities here: The app can choose to insert a seek event
on the filesrc element (byte offset), it can insert a byte/time offset
seek on the video_0 pad of mpeg2parse or it can insert a time seek event
on mpeg2decs src pad.

the event will travel upstream using the handlers and the intermediate
elements can convert the event from a time to a byte offset (possibly
using GstTimeCache to speed up things).

Filesrc will get a byte seek event on its src pad and will proceed as
in case 2.

As can be seen from this example the app will generate an event in another
context than those of the plugins, so this will need proper locking.

The app can also choose to insert a flush event on one of the src
pads. The plugins would clear their cached data and forward the event
to their upstream peer pad(s).

4)...

Insert impossible case here..