[gst-devel] event system

[Thomas Vander Stichele]

I've been thinking about a possible event system based on some of the
things omega and wtay told me yesterday, and I would like to spark some
discussion as I have some ideas on how to do it, though I'm not sure if
they're all good of course.

So here's a rundown of the general issues and my ideas on them.

1) first of all, events can travel two ways : from left to right, ie
following the data stream, or right to left, ie downstream.
Here's the some events that could/should be possible :
	- eos : end of stream, travels downstream
	- qos : quality of service, upstream, downstream plugin can ask to
		send data faster or slower
	- flush : sent downstream; eg. a src plugin could ask an mp3
		encoder to flush out a full frame and clear it's
		sample memlory and maybe even change encoding parameters
	- clear : could be bidirectional; for example a plugin could ask
		  to clear all the queues of data
	- seek : sent upstream; plugin asks upstream plugin to go to a
	         specific place
        - speed : upstream; downstream plugin asks upstream plugins to
		 send data at a different speed, allowing fast-forward or
		 reverse

2) Most events will need to send a little, but not much, extra data.  I
think all of them could use only one variable, and work in the same way as
the current gtk arguments.  If not, they could work with a simple struct.

3) These events shouldn't be user-definable IMO; if there is need for new
types of events, they should be tied to the gstreamer core as to ensure a
well-defined set of events.

4) IMO, for downstream events, a plugin should either only send an event
*or* a data buffer, but not both at the same time, as to make it easier on
plugin writers.  I'm not sure this really should be a requirement, but it
seems like a good rule of thumb unless there are counterexamples.  In any
case, I would let a plugin send only one event at a time.

5) As to how events should be passed on :
* for downstream events : I would tie a new variable to the src pad, which
would be a struct with an enum for the type of data that's passed through
in it's iteration.
The enum would be { DATA, EVENT_NODATA, EVENT_EOS, EVENT_FLUSH, ... }
The enum would be checked by the next plugin; if it's DATA, then it works
as it is now, but the buffer pointer would be in the event struct.
if it's another, and it also has a parameter, that parameter would be in
the struct as well, probably in the same way as gtk arguments are handled
now.  

If the overhead introduced by this struct is too large compared to
the current case, maybe the struct could be split up; an IS_DATA boolean
macro could be sent out which should be checked.  If it is data, as is the
general case, then use the standard mechanism, because the buffer ptr will
actually point to data.  If it's false, then use the above-mentioned
struct.

* for upstream events: roughly the same approach, but in this case the
enum would probably never be set to DATA, and it would be tied to it's
sink pad.

6) plugins should proxy all of these events by default automatically.
Only plugins that specifically know the event has a meaning for them
should install event handlers.

7) As to how a higher-level thread or pipeline would be signalled of the
event; I think the basic approach as outlined in docs/random/eos could be
used for this; I'm just not sure it would actually be useful for all types
of events.  But I'm not worrying about that just yet ;)

So, that's my opinion on it.  Anyone care to comment or present different
cases ?

BTW, I've added a decent eos handler to the afsink element, so you can now
use this to write .wav's or .aiff's to disk.

thomas

<-*-                      -*->
I'd like to tell you how I feel
I'll probably keep it till a Saturday
<-*- thomas at apestaart.org -*->
URGent, the best radio on the Internet - 24/7 ! - http://urgent.rug.ac.be/