commit 35c9457fb41618bf9aa02bf2eda7ea355bea78bf
Author: Thomas Schöpping <tschoepp@cit-ec.uni-bielefeld.de>
Date:   Mon Oct 22 12:24:27 2018 +0200

    Finalized (hopefully) the documentation/specification.

diff --git a/doc/classdiagrams/overview.uml b/doc/classdiagrams/overview.uml
index 460fa41..9237392 100644
--- a/doc/classdiagrams/overview.uml
+++ b/doc/classdiagrams/overview.uml
@@ -54,12 +54,44 @@ package "primitives" {
     uint64_t
   }
 
+  /' Just a function for debugging. '/
+  class urt_debug <<(F,white)>> {
+      'Checks the condition in debug mode.
+    + urtDebugAssert(condition : bool) : void
+  }
+
+  /' Node synchronization type. '/
+  class urt_nodesync_t <<T,lightblue>> {
+    'configurable
+    uin8_t
+    .. or ..
+    int8_t
+    .. or ..
+    uint16_t
+    .. or ..
+    int16_t
+    .. or ..
+    uint32_t
+    .. or ..
+    int32_t
+    .. or ..
+    uint64_t
+    .. or ..
+    int64_t
+  }
+
 } /' package "primitives" '/
 
 
 
 package "interfaces" {
 
+  /' Not a type but a set of configuration macros. '/
+  class urt_config <<(C,grey)>> {
+      'Selection to en-/disable debug checks.
+    + URT_CONFIG_DEBUG : bool
+  }
+
   /' OS time type with arbitrary resolution. '/
   class urt_osTime_t <<(T,lightblue)>> {
       'Converts an OS time to 64 bit microsecond precise value.
@@ -151,6 +183,22 @@ package "interfaces" {
       URT_THREAD_TERMINATE_KILL = 9
     }
 
+    /' Thread execution states. '/
+    enum urt_osThreadState_t {
+      'Thread is currently being executed.
+      URT_THREAD_STATE_RUNNING = 0
+      'Thread is ready but waiting to be scheduled.
+      URT_THREAD_STATE_READY = 1
+      'Thread is actively sleeping.
+      URT_THREAD_STATE_SLEEPING = 2
+      'Thread has ben suspended explicitely.
+      URT_THREAD_STATE_SUSPENDED = 3
+      'Thread is waiting for something (e.g. Mutex, event, etc.).
+      URT_THREAD_STATE_WAITING = 4
+      'Thread has terminated.
+      URT_THREAD_STATE_TERMINATED = 5
+    }
+
     /' OS thread interface. '/
     class urt_osThread_t <<(T,lightblue)>> {
         'Minimum priority for low priority threads.
@@ -180,7 +228,7 @@ package "interfaces" {
       + URT_THREAD_MAX_USLEEP : unsigned int
       __
         'Macro to setup working area as static variable (handles alignment if required).
-      + URT_THREAD_WORKING_AREA (var : varname, stacksize : size_t)
+      + URT_THREAD_WORKING_AREA (varname, stacksize)
       ..
         'Initializes an urt_osThread_t object.
       + urtThreadInit (wa : void*, wasize : size_t, func : urt_osThreadFunction_t*, arg : void*) : urt_osThread_t*
@@ -193,13 +241,7 @@ package "interfaces" {
         'Sets the priority of a thread.
       + urtThreadSetPriority (thread : urt_osThread_t*, prio : urt_osThreadPrio_t) : void
         'Retrieves the first thread in the list of children.
-      + urtThreadGetChildren (thread : urt_osThread_t*) : urt_osThread_t*
-        'Retrieves the parent thread.
-      + urtThreadGetParent (thread : urt_osThread_t*) : urt_osThread_t*
-        'The calling threads suspends execution until it is woken up by calling urtTheadResume().
       + urtThreadSuspend (void) : void
-        'Retrieves whether a  thread is currently suspended.
-      + urtThreadIsSuspended (thread : urt_osThread_t*) : bool
         'Wakes a suspended thread.
       + urtThreadResume (thread : urt_osThread_t*) : urt_status_t
         'Suspends the calling thread for the specified time.
@@ -218,18 +260,28 @@ package "interfaces" {
       + urtThreadTerminate (thread : urt_osThread_t*, sig : urt_osThreadTerminateSignal_t) : void
         'Waits until the specified thread terminates.
       + urtThreadJoin (thread : urt_osThread_t*) : void
+        'Retrieves the execution state of the specified thread.
+      + urtThreadGetState (thread : urt_osThread_t*) : urt_osThreadState_t
+        'Retrieves the first child of a thread (or ""NULL"").
+      + urtThreadGetChildren (thread : urt_osThread_t*) : urt_osThread_t*
+        'Retrieves a sibling (next child in a list) of the thread or ""NULL"".
+      + urtThreadGetSibling (thread : urt_osThread_t*) : urt_psThread_t*
     }
     urt_osThread_t ..> urt_osThreadPrio_t
     urt_osThread_t ..> urt_osThreadFunction_t
     urt_osThread_t ..> urt_osTime_t
     urt_osThread_t ..> urt_osThreadTerminateSignal_t
+    urt_osThread_t ..> urt_osThreadState_t
 
   } /' package "thread" '/
 
   package "events" {
 
     /' OS event mask type. '/
-    class urt_osEventMask_t <<(T,lightblue)>>
+    class urt_osEventMask_t <<(T,lightblue)>> {
+        'The event mask, which will be handled with maximum priority by the event system.
+      + URT_EVENTMASK_MAXPRIO : urt_osEventMask_t
+    }
 
     /' OS event flag type. '/
     class urt_osEventFlags_t <<(T,lightblue)>>
@@ -278,6 +330,14 @@ package "interfaces" {
 
   } /' package "events" '/
 
+  /' Not a class/type but a set of output-related functions. '/
+    class urt_streams <<(F,white)>> {
+        'Prints a formatted string to the standard output stream (stdout).
+      + urtPrintf(fmt : char*, ... ) : int
+        'Prints a formatted string to the standard error stream (stderr).
+      + urtErrPrintf(fmt : char*, ... ) : int
+    }
+
 } /' package "interfaces" '/
 
 package "middleware" {
@@ -464,7 +524,7 @@ package "middleware" {
       'Pointer to the next topic in a list.
     + next : urt_topic_t*
       'Mutex lock for exclusive access.
-    + mutex : urt_osMutex_t
+    + lock : urt_osMutex_t
       'Event source to inform all subscribers when a new message is published.
     + evtSource : urt_osEventSource_t
       'Number of HRT subscribers.
@@ -487,8 +547,6 @@ package "middleware" {
     __
       'Initializes an urt_topic_t object.
     + urtTopicInit (topic : urt_topic_t*, id : urt_topicid_t) : urt_status_t
-      'Appends the given list of messages to the topic's buffer.
-    + urtTopicContributeMessages (topic : urt_topic_t*, messages : urt_message_t*) : void
   }
   urt_topic_t "1" o-- "0..1" urt_topic_t
   urt_topic_t "1" *-- "1" urt_osMutex_t
@@ -507,35 +565,44 @@ package "middleware" {
     - {static} _nodes : urt_node_t*
       'List of topics ordered by their identifiers.
     - {static} _topics : urt_topic_t*
+      'Event source for control events.
+    - {static} _evtSource : urt_osEventSource_t
+      'Mutex used for synchronization.
+    - {static} _lock : urt_osMutex_t
     __
       'Initializes the urt_core_t object.
     + urtCoreInit (void) : urt_status_t
-      'Starts all nodes.
-    + urtCoreStartAll (void) : urt_status_t
+      'Starts all node threads (nodes will block before the loop).
+    + urtCoreStartNodes (void) : urt_status_t
+      'Nodes can use this function to synchronize globally.
+    + urtCoreSynchronizeNodes (node : urt_node_t*, stage : urt_nodesync_t) : urt_status_t
       'Stops all nodes.
-    + urtCoreStopAll (void) : urt_status_t
+    + urtCoreStopNodes (void) : urt_status_t
       'Retrieves a topic given an identifier.
     + urtCoreRetrieveTopic (id : urt_topicid_t) : urt_topic_t*
   }
   urt_core_t "1" o-- "0..*" urt_topic_t
   urt_core_t "1" o-- "0..*" urt_node_t
+  urt_core_t "1" *-- "1" urt_osEventSource_t
+  urt_core_t "1" *-- "1" urt_osMutex_t
   urt_core_t ..> urt_status_t
+  urt_core_t --> urt_nodesync_t
   urt_core_t ..> urt_topicid_t
 
   package "node" {
 
     /' Function type to be called during setup phase of node threads. '/
     class urt_nodeSetupCallback_t <<(T,lightblue)>> {
-      'Takes the node and optional parameters as arguments.
-      urt_nodeSetupCallback_t (node : urt_node_t*, arg : void*) : urt_status_t
+      'Takes the node and optional parameters as arguments and returns a event mask for the next iteration.
+      urt_nodeSetupCallback_t (node : urt_node_t*, arg : void*) : urt_osEventMask_t
     }
     urt_nodeSetupCallback_t ..> urt_node_t
     urt_nodeSetupCallback_t ..> urt_status_t
 
     /' Function type to be called during loop phase of node threads. '/
     class urt_nodeLoopCallback_t <<(T,lightblue)>> {
-      'Takes the node, a mask of occurred events and optional parameters as arguments.
-      urt_nodeLoopCallback_t (node : urt_node_t*, events : urt_osEventMask_t, arg : void*) : urt_status_t
+      'Takes the node, a mask of occurred events and optional parameters as arguments and returns a event mask for the next iteration.
+      urt_nodeLoopCallback_t (node : urt_node_t*, events : urt_osEventMask_t, arg : void*) : urt_osEventMask_t
     }
     urt_nodeLoopCallback_t ..> urt_node_t
     urt_nodeLoopCallback_t ..> urt_osEventMask_t
@@ -555,26 +622,24 @@ package "middleware" {
       + loopcallback : urt_nodeLoopCallback_t*
         'Optional parameters for the loop callback function.
       + loopparams : void*
-        'A mask for which events to wait.
-      + waitmask : urt_osEventMask_t
-        'How the node will wait for events.
-      + waittype : urt_osEventWaitType_t
+        'Execution stage of the node.
+      + stage : urt_nodesync_t
+        'Event listener for middleware-wide control events.
+      + listener : urt_osEventListener_t
       __
       'The main() function of the node thread.
       - {static} _main : urt_osThreadFunction_t
         'Initializes an urt_node_t object.
       + urtNodeInit (node : urt_node_t*, stacksize : size_t, setupcallback : urt_nodeSetupCallback_t*, setupparams : void*, loopcallback : urt_nodeLoopCallback_t*, loopparams : void*) : urt_status_t
-        'Terminate a node thread and all its child threads (if any).
-      + urtNodeTerminateRecusively (node : urt_node_t*, sig : urt_osThreadTerminateSignal_t) : void
-        'Wait for a node thread an all its child threads (if any) to terminate.
-      + urtNodeJoinRecursively (node : urt_node_t*) : void
     }
     urt_node_t "1" o-- "0..1" urt_node_t
     urt_node_t "1" o-- "1" urt_osThread_t
     urt_node_t "1" o-- "1" urt_nodeSetupCallback_t
     urt_node_t "1" o-- "1" urt_nodeLoopCallback_t
+    urt_node_t "1" *-- "1" urt_nodesync_t
     urt_node_t "1" *-- "1" urt_osEventMask_t
     urt_node_t "1" *-- "1" urt_osEventWaitType_t
+    urt_node_t "1" *-- "1" urt_osEventListener_t
     urt_node_t ..> urt_osThreadTerminateSignal_t
 
   } /' package "node" '/
