agent: Add assertions to check component state transitions are valid

There is no point in the NiceComponents having a state machine if the
state transition graph is not documented or enforced. Document and
enforce it.

http://phabricator.freedesktop.org/T120

3 files changed, 33 insertions, 2 deletions

diff --git a/docs/reference/libnice/Makefile.am b/docs/reference/libnice/Makefile.am
index 1d53e3b..19e479e 100644
--- a/docs/reference/libnice/Makefile.am
+++ b/docs/reference/libnice/Makefile.am
@@ -62,7 +62,7 @@ IGNORE_HFILES= conncheck.h discovery.h stream.h component.h agent-priv.h \
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
-HTML_IMAGES=
+HTML_IMAGES = states.png
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
@@ -94,13 +94,19 @@ include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
-#EXTRA_DIST +=
+EXTRA_DIST += states.gv
 
 # Files not to distribute
 # for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
 # for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
 #DISTCLEANFILES +=
 
+# If we ever need to regenerate this diagram.
+# Since it’s not expected to change much, let’s not depend on GraphViz to
+# build the docs.
+states.png: states.gv
+	dot -Tpng -Gsize=9.6,2.9\! -Gdpi=200 $^ > $@
+
 if ENABLE_GTK_DOC
 TESTS_ENVIRONMENT = cd $(builddir) &&
 TESTS = $(GTKDOC_CHECK)
diff --git a/docs/reference/libnice/states.gv b/docs/reference/libnice/states.gv
new file mode 100644
index 0000000..609be2e
--- /dev/null
+++ b/docs/reference/libnice/states.gv
@@ -0,0 +1,25 @@
+/* libnice state transition diagram for NiceComponentState. */
+digraph NiceComponentState {
+	rankdir=TB;
+	node [shape = doublecircle]; DISCONNECTED;
+	node [shape = circle];
+
+	/* Colour the normal control flow in green. */
+	DISCONNECTED -> GATHERING [ label = "nice_agent_gather_candidates()", color = chartreuse3 ];
+	GATHERING -> CONNECTING [ label = "nice_agent_set_remote_candidates()", color = chartreuse3 ];
+	CONNECTING -> CONNECTED [ label = "At least one candidate pair succeeds", color = chartreuse3 ];
+	CONNECTED -> READY [ label = "All candidate pairs checks finished", color = chartreuse3 ];
+
+	READY -> CONNECTED [ label = "Selected candidate pair fails" ];
+
+	FAILED -> CONNECTING [ label = "nice_agent_set_remote_candidates()" ];
+
+	DISCONNECTED -> CONNECTING [ label = "nice_agent_set_remote_candidates()" ];
+
+	/* Colour the failure paths in grey. */
+	DISCONNECTED -> FAILED [ label = "Failure", color = gray ];
+	GATHERING -> FAILED [ label = "Failure", color = gray ];
+	CONNECTING -> FAILED [ label = "Failure", color = gray ];
+	CONNECTED -> FAILED [ label = "Failure", color = gray ];
+	READY -> FAILED [ label = "Failure", color = gray ];
+}
diff --git a/docs/reference/libnice/states.png b/docs/reference/libnice/states.png
new file mode 100644
index 0000000..ba23739
--- /dev/null
+++ b/docs/reference/libnice/states.png