AMiRo-OS

/'

µRtWare is a lightweight publish/subscribe middleware for real-time

applications. It was developed as part of the software habitat for the

Autonomous Mini Robot [1] (AMiRo) but can be used for other purposes as well.

Copyright (C) 2018..2020  Thomas Schöpping et al.

This program is free software: you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation, either version 3 of the License, or

(at your option) any later version.

This program is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program.  If not, see <http://www.gnu.org/licenses/>.

'/

/'### INTRO ##################################################################'/

@startuml

title **µRtWare**\nPublish-Subscribe System

!include ../functions.iuml

/'### ENTITIES ###############################################################'/

!startsub ENTITIES

/' Message type. '/

$structure("urt_message_t") {

    'Pointer to the next message in a list.

  + {field} next : urt_message_t*

    'Pointer to some arbitrary (reusable) payload object.

  + {field} payload : void*

    'Origin time of the message.

  + {field} originTime : urt_osTime_t

    'Mutex lock for exclusive access.

  + {field} lock : urt_osMutex_t

    'Counter of HRT subscribers that did not consume the message yet.

  + {field} numHrtConsumersLeft : unsigned int

  .. URT_CFG_PUBSUB_PROFILING == true ..

    'Counter of overall subscribers that did not consume the message yet.

  + {field} numConsumersLeft : unsigned int

  __

    'Initializes a urt_message_t object.

  + {method} urtMessageInit (message : urt_message_t*, payload : void*) : urt_status_t

}

$group("subscriber") {

  $group("real-time constraint data") {

    /' The top level RT constraints structure. '/

    $structure("urt_rtdata_t") {

        'The actual RT constraint class.

      + {field} class : urt_rtconstraintclass_t

        'Parameters of the RT constraints.

      + {field} params : urt_rtconstraintsparams_t

    }

    /' Descriptor to distinguish the four RT classes. '/

    $enumeration("urt_rtclass_t") {

        'Hard real-time.

      URT_RTCLASS_HARD = 0

        'Firm real-time.

      URT_RTCLASS_FIRM = 1

        'Soft real-time.

      URT_RTCLASS_SOFT = 2

        'No real-time at all.

      URT_RTCLASS_NONE = 3

    }

    /' Union structure, holding RT constraints parameters. '/

    $union("urt_rtclassdata_t") {

        'Parameters for hard real-time.

      + {field} hrt : urt_hrtparams_t

        'Parameters for firm real-time.

      + {field} frt : urt_frtparams_t

        'Parameters for soft real-time.

      + {field} srt : urt_srtparans_t

        'Parameters for non-real-time.

      + {field} nrt : urt_nrtparams_t

    }

    /' Parameters for hard real-time. '/

    $structure("urt_hrtdata_t") {

        'Pointer to the next HRT subscriber in a list.

      + {field} next : urt_subscriber_t*

      .. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true ..

        'QoS Timer to detect missed deadlines.

      + {field} qosDeadlineTimer : urt_osTimer_t

        'Maximum temporal offset between creation and consumption of messages.

      + {field} deadlineOffset : urt_delay_t

      .. URT_CFG_PUBSUB_QOS_RATECHECKS == true ..

        'Expected rate at which data is published.

      + {field} expectedRate : urt_delay_t

      .. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true ..

        'Maximum expected jitter.

      + {field} maxJitter : urt_delay_t

        'Minimum latency ever detected (to calculate jitter).

      + {field} minLatency : urt_delay_t

        'Maximum latency ever detected (to calculate jitter).

      + {field} maxLatency : urt_delay_t

    }

    /' Parameters for firm real-time. '/

    $structure("urt_frtdata_t") {

      .. URT_CFG_PUBSUB_QOS_DEADLINECHECKS == true ..

        'Maximum temporal offset between creation and consumption of messages.

      + {field} deadlineOffset : urt_delay_t

      .. URT_CFG_PUBSUB_QOS_RATECHECKS == true ..

        'Expected rate at which data is published.

      + {field} expectedRate : urt_delay_t

      .. URT_CFG_PUBSUB_PROFILING == true || URT_CFG_PUBSUB_QOS_JITTERCHECKS == true ..

        'Maximum expected jitter.

      + {field} maxJitter : urt_delay_t

        'Minimum latency ever detected (to calculate jitter).

      + {field} minLatency : urt_delay_t

        'Maximum latency ever detected (to calculate jitter).

      + {field} maxLatency : urt_delay_t

    }

    $group("SRT data") {

      /' Function type to be called when calculating the usefulness of a message. '/

      $function("urt_srtusefulnessfunc_t") {

          'Takes a delay and optionally parameters as arguments and returns a float in [0, 1].

        urt_srtusefulnessfunc_t (dt : urt_delay_t, params : void*) : float

      }

      /' Parameters for soft real-time. '/

      $structure("urt_srtdata_t") {

          'Callback to calculate usefulness of a message

        + {field} usefullnesscb : urt_srtusefulnessfunc_t*

          'Optional parameters for the callback function.

        + {field} cbparams : void*

      }

    } /'SRT data'/

    /' Parameters for non-real-time. '/

    $structure("urt_nrtdata_t") {

      'There are nor parameters in this case.

    }

  } /'real-time constraint data'/

  /' Subscriber type. '/

  $structure("urt_subscriber_t") {

      'Pointer to the topic, this subscriber subscribed to.

    + {field} topic : urt_topic_t*

      'Event listener to notify the node about new messages.

    + {field} evtListener : urt_osEventListener_t

      'Real-time class descriptor.

    + {field} rtdata : urt_rtdata_t

      'Pointer to the message consumed most recently.

    + {field} lastMessage : urt_message_t*

      'Copy of the origin time of the message consumed most recently.

    + {field} lastMessageTime : urt_osTime_t

    .. URT_CFG_PUBSUB_PROFILING == true ..

      'Sum of all latencies.

    + {field} sumLatencies : uint64_t

      'Number of messages received.

    + {field} numMessagesReceived : uint64_t

    .. URT_CFG_PUBSUB_PROFILING == true ..

      'Minimum latency ever detected (to calculate jitter).

    + {field} minLatency : urt_delay_t

      'Maximum latency ever detected (to calculate jitter).

    + {field} maxLatency : urt_delay_t

    __

      'Initializes a urt_subscriber_t object.

    + {method} urtSubscriberInit (subscriber : urt_subscriber_t*) : urt_status_t

      'Tries to subscribe to a topic as HRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic.

    + {method} urtSubscriberSubscribeHrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, deadline : urt_delay_t, rate : urt_delay_t, jitter : urt_delay_t) : urt_status_t

      'Tries to subscribe to a topic as FRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic.

    + {method} urtSubscriberSubscribeFrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, deadline : urt_delay_t, rate : urt_delay_t, jitter : urt_delay_t) : urt_status_t

      'Tries to subscribe to a topic as SRT subscriber, sets all according parameters and optionally contributes a list of messages to the topic.

    + {method} urtSubscriberSubscribeSrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*, usefulnesscb : urt_srtusefulnessfunc_t*, cbparams : void*) : urt_status_t

      'Tries to subscribe to a topic as NRT subscriber and optionally contributes a list of messages to the topic.

    + {method} urtSubscriberSubscribeNrt (subscriber : urt_subscriber_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t

      'Unsubscribes from a topic.

    + {method} urtSubscriberUnsubscribe (subscriber : urt_subscriber_t*) : urt_status_t

      'Fetches the next message in the buffer, optionally copies the payload and optionally returns the latency.

    + {method} urtSubscriberFetchNextMessage (subscriber : urt_subscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t

      'Fetches the latest message, optionally copies the payload and optionally returns the latency.

    + {method} urtSubscriberFetchLatestMessage (subscriber : urt_subscriber_t*, payload : void*, bytes : size_t, latency : urt_delay_t*) : urt_status_t

      'Calculates the usefulness of a message after the specified delay depending on the SRT or FRT (or HRT) parameters.

    + {method} urtSubscriberCalculateUsefulness (subscriber : urt_subscriber_t*, latency : urt_delay_t) : float

  }

} /'subscriber'/

/' Publisher type. '/

$structure("urt_publisher_t") {

    'Pointer to the topic for publishing.

  + {field} topic : urt_topic_t*

  .. URT_CFG_PROFILING == true ..

    'Counter of attempts to publish a message.

  + {field} publishAttempts : uint64_t

    'Counter of failed attempts to publish a message.

  + {field} publishFails : uint64_t

  __

    'Initializes a urt_publisher_t object and contributes an optional list of messages.

  + {method} urtPublisherInit (publisher : urt_publisher_t*, topic : urt_topic_t*, messages : urt_message_t*) : urt_status_t

    'Publishes a message via the associated topic.

  + {method} urtPublisherPublish (publisher : urt_publisher_t*, payload : void*, n : size_t, t : urt_osTime_t, timeout : urt_delay_t) : urt_status_t

}

/' Topic type. '/

$structure("urt_topic_t") {

    'Pointer to the next topic in a list.

  + {field} next : urt_topic_t*

    'Identifier of the topic.

  + {field} id : urt_topicid_t

    'Mutex lock for exclusive access.

  + {field} lock : urt_osMutex_t

    'Event source to inform all subscribers when a new message is published.

  + {field} evtSource : urt_osEventSource_t

    'Number of HRT subscribers.

  + {field} numHrtSubscribers : unsigned int

    'List of HRT subscribers, orderd by their expected rate (most critical first).

  + {field} hrtSubscribers : urt_subscriber_t*

    'Condition variable to inform waiting publishers when a blocked message becomes available.

  + {field} hrtReleased : urt_osCondvar_t

    'Mandatory message, each Topic holds.

  + {field} mandatoryMessage : urt_message_t

    'Pointer to the latest message.

  + {field} latestMessage : urt_message_t*

  .. URT_CFG_PUBSUB_QOS_RATECHECKS == true ..

    'Timer to check for missed rates.

  + {field} qosRateTimer : urt_osTimer_t

  .. URT_CFG_PUBSUB_PROFILING == true ..

    'Variable to count how many (non-hrt) subscribers did not fetch a message before it was reused.

  + {field} numDiscardedMessages : uint64_t

    'Number of overall subscribers.

  + {field} numSubscribers : unsigned int

  __

    'Initializes an urt_topic_t object.

  + {method} urtTopicInit (topic : urt_topic_t*, id : urt_topicid_t) : urt_status_t

}

!endsub

/'### DEPENDENCIES & LAYOUT ##################################################'/

!startsub DEPENDENCIES

urt_srtdata_t "1" o-- "0..1" urt_srtusefulnessfunc_t

urt_rtclassdata_t "1" *-- "0..1" urt_hrtdata_t

urt_rtclassdata_t "1" *-- "0..1" urt_frtdata_t

urt_rtclassdata_t "1" *-- "0..1" urt_srtdata_t

urt_rtclassdata_t "1" *-- "0..1" urt_nrtdata_t

urt_rtdata_t "1" *-- "1" urt_rtclass_t

urt_rtdata_t "1" *-- "1" urt_rtclassdata_t

urt_hrtdata_t "1" o-up- "0..1" urt_subscriber_t

urt_message_t "1" o-- "0..1" urt_message_t

urt_subscriber_t "1" *-- "1" urt_rtdata_t

urt_subscriber_t "1" o- "0..1" urt_topic_t

urt_subscriber_t "1" o-- "0..1" urt_message_t

urt_publisher_t "1" o- "1" urt_topic_t

urt_publisher_t ..> urt_message_t

urt_topic_t "1" o-- "0..1" urt_topic_t

urt_topic_t "1" o- "0..1" urt_subscriber_t

urt_topic_t "1" o-- "1..1" urt_message_t

urt_topic_t "1" *-- "1" urt_message_t

!endsub

/'### OUTRO ##################################################################'/

@enduml