The Application Development Manual encourages handling dynamic pads (such as a demuxer's) by watching for the pad-added signal and linking to downstream elements as needed.  Unfortunately, it neglects to mention that when adding the new downstream elements to the pipeline, things may not work unless the children's states are synced with their parent.

After a day of investigating a pipeline that would sometimes inexplicably freeze and sometimes (if I rearranged my code) work, I found this post:

http://web.archiveorange.com/archive/v/8yxpz7FmOlGqxVYtkPb4

...in which the author recommends calling gst_element_sync_state_with_parent() on a newly-added element after it is added to a bin and before linking it to a dynamic pad.  Sure enough, that solved the problem.  I went back to the Manual and checked the most obvious places:

http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/chapter-pads.html
http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-intro-basics-bins.html
http://gstreamer.freedesktop.org/data/doc/gstreamer/head/manual/html/section-elements-states.html

Unless I'm blind, none of them mentions this issue.  I hope someone will add clear documentation on this state sync requirement, preferably in several places.  Knowing about it would have made my day a lot easier.