Phonon State Machine

[Trever Fischer]

Howdy, all.

Harald and I have been discussing implementing and documenting a
well-defined state machine for Phonon, hopefully this is something we can
work on at Randa.

I've created a diagram showing the current mess of states in Phonon:
http://i.imgur.com/ccdC0.png

It illustrates how states are apparently implemented, how GStreamer
implements them, and how various applications expect them to behave. Keep
in mind that backends are expected to implement this currently undefined
state machine to provide a consistent view for all applications.

There is a slight difference between the top and bottom halves. The top
half is an internal design, whilst the bottom is the state changes
apparent in the applications. By internal design, I mean how the internal
state machine behaves.

Looking at the "New Phonon" diagram, you can see a much more concise and
rigorous state machine. Here, the states represent what the MediaObject's
state() method should return. The MediaObject starts out in Stopped. The
only way to get to Playing is to first go through Paused, thereby entering
the "doing stuff" sub-machine. While the pipeline is doing stuff, it
implies that media is moving (or ready to be moved) through the pipeline.
Things are seekable, you can query metadata, etc.

While in the Playing state, setting a new source via setSource implies a
transition out of the Doing Stuff state and to the Loading state. To get
there, one leaves the DoingStuff state by entering paused, then stopped,
finally Loading.

After a new source is set (and stateChanged(Loading) is emitted), Phonon
enters the Stopped state.

Due to how API consumers use phonon, it is likely backwards incompatible
to emit stateChanged() at each transition. I propose only emitting
stateChanged once we've reached the final state. Beyond maintaining
backwards compatibility, there is a bit of rationale behind that decision.
It shouldn't be required that all multimedia players keep track of the
target state while ignoring intermediate states. Otherwise, one ends up
with the play/pause buttons switching back and forth while a media source
is loaded. Once a mediaobject has entered Loading from Playing, it should
automatically resume the last state it was in prior to making its way to
Playing.

Cleaning up these states is pretty important to fixing a lot of the
brokeness in phonon-gstreamer. Only after combing through the code can you
really get a feel for what states actually mean and what actions are
supported. There's no doubt that applications can benefit from a well
documented state machine, which would give more predictability to Phonon.

-- 
Trever Fischer (tdfischer)
Fedora Ambassador, KDE Hacker
http://wm161.net
GPG: C40F2998 hkp://wwwkeys.pgp.net