From a67aaef8c73ee3a7c4c0ea36b344ea952576d3a7 Mon Sep 17 00:00:00 2001
From: Stein Magnus Jodal <stein.magnus@jodal.no>
Date: Fri, 20 Aug 2010 03:08:59 +0200
Subject: [PATCH] Update class instantiation/usage graph

---
 docs/development/internals.rst | 99 ++++++++++++++++++++++++++--------
 1 file changed, 76 insertions(+), 23 deletions(-)

diff --git a/docs/development/internals.rst b/docs/development/internals.rst
index 085b55ac..73dc59e6 100644
--- a/docs/development/internals.rst
+++ b/docs/development/internals.rst
@@ -12,40 +12,93 @@ In addition to what you'll find here, don't forget the :doc:`/api/index`.
 Class instantiation and usage
 =============================
 
-The following diagram shows how Mopidy with the despotify backend and ALSA
-mixer is wired together. The gray nodes are part of external dependencies, and
-not Mopidy. The red nodes lives in the ``main`` process (running an
-:mod:`asyncore` loop), while the blue nodes lives in a secondary process named
-``core`` (running a service loop in :class:`mopidy.core.CoreProcess`).
+The following diagram shows how Mopidy is wired together with the MPD client,
+the Spotify service, and the speakers.
+
+**Legend**
+
+- Filled red boxes are the key external systems.
+- Gray boxes are external dependencies.
+- Blue circles lives in the ``main`` process, also known as ``CoreProcess``.
+  It processing messages on the core queue.
+- Purple circles lives in a process named ``MpdProcess``, running an
+  :mod:`asyncore` loop.
+- Green circles lives in a process named ``GStreamerProcess``.
+- Brown circle is a thread living in the ``CoreProcess``.
 
 .. digraph:: class_instantiation_and_usage
 
-    "spytify" [ color="gray" ]
-    "despotify" [ color="gray" ]
-    "alsaaudio" [ color="gray" ]
-    "__main__" [ color="red" ]
+    "main" [ color="blue" ]
     "CoreProcess" [ color="blue" ]
-    "DespotifyBackend" [ color="blue" ]
-    "AlsaMixer" [ color="blue" ]
+
+    # Frontend
+    "MPD client" [ color="red", style="filled", shape="box" ]
     "MpdFrontend" [ color="blue" ]
-    "MpdServer" [ color="red" ]
-    "MpdSession" [ color="red" ]
-    "__main__" -> "CoreProcess" [ label="create" ]
-    "__main__" -> "MpdServer" [ label="create" ]
-    "CoreProcess" -> "DespotifyBackend" [ label="create" ]
+    "MpdProcess" [ color="purple" ]
+    "MpdServer" [ color="purple" ]
+    "MpdSession" [ color="purple" ]
+    "MpdDispatcher" [ color="blue" ]
+
+    # Backend
+    "Libspotify\nBackend" [ color="blue" ]
+    "Libspotify\nSessionManager" [ color="brown" ]
+    "pyspotify" [ color="gray", shape="box" ]
+    "libspotify" [ color="gray", shape="box" ]
+    "Spotify" [ color="red", style="filled", shape="box" ]
+
+    # Output/mixer
+    "GStreamer\nOutput" [ color="blue" ]
+    "GStreamer\nSoftwareMixer" [ color="blue" ]
+    "GStreamer\nProcess" [ color="green" ]
+    "GStreamer" [ color="gray", shape="box" ]
+    "Speakers" [ color="red", style="filled", shape="box" ]
+
+    "main" -> "CoreProcess" [ label="create" ]
+
+    # Frontend
     "CoreProcess" -> "MpdFrontend" [ label="create" ]
-    "MpdServer" -> "MpdSession" [ label="create one per client" ]
-    "MpdSession" -> "MpdFrontend" [ label="pass MPD requests to" ]
-    "MpdFrontend" -> "DespotifyBackend" [ label="use backend API" ]
-    "DespotifyBackend" -> "AlsaMixer" [ label="create and use mixer API" ]
-    "DespotifyBackend" -> "spytify" [ label="use Python wrapper" ]
-    "spytify" -> "despotify" [ label="use C library" ]
-    "AlsaMixer" -> "alsaaudio" [ label="use Python library" ]
+    "MpdFrontend" -> "MpdProcess" [ label="create" ]
+    "MpdProcess" -> "MpdServer" [ label="create" ]
+    "MpdServer" -> "MpdSession" [ label="create one\nper client" ]
+    "MpdSession" -> "MpdDispatcher" [
+        label="pass requests\nvia core_queue" ]
+    "MpdDispatcher" -> "MpdSession" [
+        label="pass response\nvia reply_to pipe" ]
+    "MpdDispatcher" -> "Libspotify\nBackend" [ label="use backend API" ]
+    "MPD client" -> "MpdServer" [ label="connect" ]
+    "MPD client" -> "MpdSession" [ label="request" ]
+    "MpdSession" -> "MPD client" [ label="response" ]
+
+    # Backend
+    "CoreProcess" -> "Libspotify\nBackend" [ label="create" ]
+    "Libspotify\nBackend" -> "Libspotify\nSessionManager" [
+        label="creates and uses" ]
+    "Libspotify\nSessionManager" -> "Libspotify\nBackend" [
+        label="pass commands\nvia core_queue" ]
+    "Libspotify\nSessionManager" -> "pyspotify" [ label="use Python\nwrapper" ]
+    "pyspotify" -> "Libspotify\nSessionManager" [ label="use callbacks" ]
+    "pyspotify" -> "libspotify" [ label="use C library" ]
+    "libspotify" -> "Spotify" [ label="use service" ]
+    "Libspotify\nSessionManager" -> "GStreamer\nProcess" [
+        label="pass commands\nand audio data\nvia output_queue" ]
+
+    # Output/mixer
+    "Libspotify\nBackend" -> "GStreamer\nSoftwareMixer" [
+        label="create and\nuse mixer API" ]
+    "GStreamer\nSoftwareMixer" -> "GStreamer\nProcess" [
+        label="pass commands\nvia output_queue" ]
+    "CoreProcess" -> "GStreamer\nOutput" [ label="create" ]
+    "GStreamer\nOutput" -> "GStreamer\nProcess" [ label="create" ]
+    "GStreamer\nProcess" -> "GStreamer" [ label="use library" ]
+    "GStreamer" -> "Speakers" [ label="play audio" ]
 
 
 Thread/process communication
 ============================
 
+.. warning::
+    This section is currently outdated.
+
 - Everything starts with ``Main``.
 - ``Main`` creates a ``Core`` process which runs the frontend, backend, and
   mixer.