Actor Framework Documents
This library provides extensions to the Actor Framework to facilitate the broadcast of messages from one actor to several others. Listeners subscribe to a message when they want to receive it from the Broadcaster, and they unsubscribe when they want to stop receiving it. The library provides a set of common interfaces that decouple Broadcasters from Listeners so any two actors in a messaging hierarchy can communicate via broadcast without having the same caller.
This library extends the Actor Framework; it does not modify the core framework in any way, so it may be used in existing projects as well as new ones.
Classifying Messages by their Intent
An actor shouldn't broadcast any kind of message anywhere; that breaks the purpose of the Actor Framework and actor-oriented design because it allows the actor to call state-changing methods on actors other than its caller and callees. When designing a message, first decide its intent. Three kinds of messaging intent were identified in this discussion:
- Command (or Request): A message sent to a callee actor to tell it to do something. Because actor-oriented design allows the recipient of this message to ignore it, cache it for later processing, or act on it at will; it may also be called a Request. In AF, Commands are implemented as simple concrete classes with both data and a method that executes an action on the recipient.
- Status (or Event): A message sent to a parent actor to notify it that something happened. Note the past-tense language! Actors aren't allowed to control their parents, so they can't send Commands up the chain; they can only notify their parents of the occurrence of something and let the parent decide how (and even whether) to handle it. In AF, these messages should be designed as loosely-coupled pairs, with an oubound class in the child actor that holds the message data and an inbound message in the parent actor that holds the message method. The parent actor's concrete message inherits from the child actor's abstract message.
- Data: A message sent anywhere that only carries data; it does not dictate what should be done with the data, nor does it imply any state information along with the data. (In contrast, Commands dictate action and Events notify state changes.) This kind of message can be safely sent to any other actor, given the recipient's unique identifier, and it can be sent with any multiplicity. In AF, that means the sender needs to have a copy of the Enqueuer for every recipient of the message. If the sender wants to broadcast the message to multiple listeners, it just needs those listeners to register their Enqueuers with him. The implementation of a Data message in AF is highly dependent on minimizing coupling between otherwise unrelated actors, so it also uses a loosely-coupled message pair like the Event message.
Documentation
Documentation for the library and the included example program is attached. A class diagram of the library's structure is provided. A "messaging diagram" is also provided to explain the runtime behavior of the example program. The messaging diagram is a UML sequence diagram that shows the lifetimes, activity states, and interactions of each actor's message handler. The user interfaces and other Actor Core.vi override behaviors for actors are not shown in the diagram. The following legend explains the conventions used in the messaging diagram:
- A box over an actor's lifetime indicates that the actor's message handler is busy and cannot process incoming messages.
- Arrows with a closed head represent synchronous interactions, like a blocking method call or a Reply Message. Arrows with open heads represent asynchronous interactions; any other type of Message.
- Right-facing solid arrows represent a caller commanding with its callee, and left-facing solid arrows represent the callee sending status to its caller.
- Dotted arrows represent the broadcast of data, which can be sent to any registered actor in the system.
Installation
The library is distributed as a VI Package. You must install VI Package Manager to install the library.
Dependencies
v1.0.0 of this library depends on the Actor Framework v4.0.1. It is provided for LV 2011 and LV 2012.
- LV 2011 users must install the Actor Framework and can download it here.
- LV 2012 users may have to upgrade the Actor Framework to v.4.0.1 and can download it here.
v1.1.0 of the library depends on the Actor Framework that is installed in <vi.lib>. It is provided for LV 2013+.
How to Use this Library
As with Actor Framework.lvlib, It is recommended that you add the library to your LV Project in order to more easily access its methods and inherit from its classes.
The library includes tools for broadcasting a data message to listeners (Broadcast Registry.lvclass), subscribing to and unsubscribing from a data broadcast (Subscription Token.lvclass), and common types for messages involved in the broadcast mechanism:
- The Registration Msg is sent from a Listener to a Broadcaster to register that listener for a data broadcast.
- The Unregistration Msg is sent to unregister a listener from a broadcast.
- The Data Msg is sent from a Broadcaster to a registered Listener when broadcasting.
In order to decouple Listeners from Broadcasters, Registration and Unregistration messages are stored inside a Subscription Token. The Subscription Token is created by a Broadcaster and shared, via messages sent through the actor call chain, with Listeners. A Listener uses methods in the Subscription Token to send Registration/Unregistration messages to the Broadcaster without having any direct coupling to that Broadcaster.
A Registration Msg holds the Listener's enqueuer and an instance of the concrete Data Msg that it will receive from the Broadcaster. When the Registration message is sent to the Broadcaster, the Broadcaster reads these elements and stores them in its Broadcast Registry to be referenced whenever it broadcasts data. An Unregistration Msg holds the Listener's enqueuer as well. When the message is sent to the Broadcaster, the Broadcaster uses the enqueuer to find and remove that Listener's registration from its Broadcast Registry.
Example Program
An example program is included with the library and can be found at <labview>\examples\Staab\AF Data Broadcasting\Simple Example\Simple Example.lvproj . It can also be found using the LabVIEW Example Finder when browsing by directory structure.
The program contains an actor that broadcasts two kinds of data, 3-axis coordinates and temperature, and listeners for each kind of data. Any number of listeners may be launched simultaneously; each will register for its broadcast and display updates in real time.
Where is the Library?
The library can be downloaded from LAVAG.org here. It is provided under the 2-clause BSD license.
mtat76 wrote:
Nice work David. So would this fall under the an actor framework implementation of the observer pattern?
I'm not falling for that trap. 
There are ten implementations of Observer and a hundred opinions on how they're each wrong. Let's just stick with "Data Broadcasting" for the title.
Edit: (I just can't shut up and leave it alone.) The more I see people trying to start their design with Patterns (capital "P"), the more I see them over-designing their software. Don't use Patterns. Learn them, try to understand their intent, and then throw the book away. Design software iteratively, with the minimal code necessary in each iteration to solve one specific, extant problem. This lets your code evolve instead of being framed up from the start, and as we've seen, evolution always wins.
As a physicist, I dealt with less-than-ideal reality all the time. But I refuse to become a software engineer until all my actors are totally decoupled -- like my design patterns book promised .
