Beginner Tutorial (Very Simple 3-Actor System)

[DMurrayIRL]

Attached is a step-by-step tutorial for beginners in Actor Framework. It's certainly not meant to be a base for writing complex programs; the aim is more to get some idea of the concepts involved by creating very simple actors and associated messaging. The coding style is my own and may not be to everyones taste, but it may make the program easier to understand, especially from a beginner viewpoint.

The program is written in LV2014, and I wouldn't know where to start in porting it to earlier versions (AF in LV2014 is somewhat different compared to previous versions, and personally I haven't used AF before this version). Also, even though the tutorial seems quite large (139 pages!), this is due to the fact that I tend to go into great detail in this style of tutorial. If you're used to AF, you could probably build this project in < 20 minutes. Also note that I don't use scripting tools (e.g. Actor framework Message Maker) in this tutorial as I believe it's better for beginners to be able to understand the basic principles in creating messages manually.

________________________________________

Draft B Update:

Added improved Stop functionality, + minor edits and typo fixes to the original.

Issue 1.0

Major overhaul following feedback from AristosQueue in this post.

[AristosQueue (NI)]

... and some just want to see what happens if they turn of reentrancy on the Do.vi method... 🙂

[Amiri]

AristosQueue wrote:

                       

... and some just want to see what happens if they turn of reentrancy on the Do.vi method... 🙂

                   

We just can't help it.

Thanks Stephen for the quick reply.

[Brainstorms]

And some wanted to see if it's practical to extend the LabVIEW Error Cluster by making it into an object (with exception handlers and logging methods added to its class)...

[Amiri]

So, what in the Actor Framework library is calling the Do.vi?

In the Actor Core UI, when I press the Calculate button and send an addition request, it uses the Enqueue.vi (from AF library) to enqueue Send Addition Request Msg and the data (number 1 and 2) and then from there the Do.vi (which sits right next to the Send Addition Request Msg.vi) gets called.

• How does this happen? What dequeues that message to call my Do.vi, the Dequeue.vi from the AF library?

• Does Actor.vi dequeue this message?

• Why have an Addition Actor.lvclass?  Why not put the Add Numbers.vi logic in the Do.vi, or just have the Add Numbers.vi method in the Addition Request Msg.lvclass?
• In my message class – why do we always have to have a message method next to the Do.vi?  Is that because if you put that logic directly in the Do.vi you would be breaking the rules of the flow?  So, do you always end up with a message class that only has two methods in it, a Do.vi and a message request type of VI or can you have multiple messages.methods sitting next to your Do.vi?  Can you explain?
• So Actor.vi is sitting at the top of all this is routing everything? Can you explain this a little bit in simple terms?  I’m trying to understand what Actor.vi is doing.

Something else that confuses me is how do I differentiate the items in the Actor Framework.lvlib that I use to build my messages and stuff from the things that are under the hood, things I shouldn't see, or be looking at?

Amiri

[Brainstorms]

Amiri wrote:

                       

So, what in the Actor Framework library is calling the Do.vi?

                   

It's called from "Actor Core.vi" when the receiving actor dequeues the message it receives that corresponds to the "Do.vi".

In the Actor Core UI, when I press the Calculate button and send an addition request, it uses the Enqueue.vi (from AF library) to enqueue Send Addition Request Msg and the data (number 1 and 2) and then from there the Do.vi (which sits right next to the Send Addition Request Msg.vi) gets called.

• How does this happen? What dequeues that message to call my Do.vi, the Dequeue.vi from the AF library?

It happens via queues, which are necessary in order to communicate data from one independent process to another (which precludes wiring data between actors, since they are independent, parallel processes).

The sending actor enqueues a message object, which may contain data; this message object is dequeued by the receiving actor.  The dequeuing occurs within the receiving actor's use of AF's "Actor Core.vi", which runs a message loop.  This message loop removes message objects from the receiver's queue as they arrive, then calls "Do.vi" with the message and the receiving actor's object.  The message's subclass overrides "Do.vi" to run a specific "Do.vi".  The key is that the override is not controlled by the actor's class, it is controlled by the message class.

Does Actor.vi dequeue this message?

No; "Actor Core.vi" dequeues it.

• Why have an Addition Actor.lvclass?  Why not put the Add Numbers.vi logic in the Do.vi, or just have the Add Numbers.vi method in the Addition Request Msg.lvclass?

Because the "Do.vi" does NOT belong to the actor's class; it belongs to the Message class instead.  The message class should not be processing the data that belongs to an actor class; the actor class's methods should do this.  This is accomplished by having the Message class's "Do.vi" call the appropriate Actor class's method.  The specific message subclass overrides to a "Do.vi" that calls the corresponding specific actor class's method.

Another reason to do it this way is because the message class's "Do.vi" can cast the incoming actor object to a parent (abstract) class, enabling the resulting actor method to be called from either the actor's class or one of the actor's ancestor classes.  It also allows abstract messages to be implemented in a straightforward fashion.

• In my message class – why do we always have to have a message method next to the Do.vi?  Is that because if you put that logic directly in the Do.vi you would be breaking the rules of the flow? 

See the above explanation.

• So, do you always end up with a message class that only has two methods in it, a Do.vi and a message request type of VI or can you have multiple messages.methods sitting next to your Do.vi?  Can you explain?

You could have more than one "Send" VI that does varied pre-processing of the message's data (such as allowing conversion of two different forms into a single form that the receiving actor expects) before sending the message object to the receiving actor.  This should be restricted to handling the data from the message class's point of view; actual manipulation of the data in the message should be left to the actor class's methods.  The "Send" methods are merely a way of "mailing" data to an actor process and invoking a specific method to process it.

• So Actor.vi is sitting at the top of all this is routing everything? Can you explain this a little bit in simple terms?  I’m trying to understand what Actor.vi is doing.

"Actor.vi" is a parent class of object that allows your actors to inherit data (enqueuers for its communication needs) and behavior (methods such as launching your actor into its own process, running a message-handling loop to dequeuing received messages, etc.)  The routing is handled by the enqueuer classes and the "Actor Core.vi" message handling loop.  You might think of "Actor.vi" as providing the framework for your actor to function, while "Actor Core.vi" provides the message routing and method invocation.

Something else that confuses me is how do I differentiate the items in the Actor Framework.lvlib that I use to build my messages and stuff from the things that are under the hood, things I shouldn't see, or be looking at?

                   

You should be using the "wizards" to create your messages -- either the Actor Framework Message Maker, the Message Project Provider, or the (now) built-in feature in LV 2015 that allows you to right-click on (one or more of) an actor's methods and automatically make messages for them.  For this reason, you should always build your actor's methods first, then create messages for them afterwards.

-t

[AristosQueue (NI)]

Amiri wrote:

• How does this happen? What dequeues that message to call my Do.vi, the Dequeue.vi from the AF library?
• Does Actor.vi dequeue this message?

                   

The correct answer probably should be "magic happens, don't worry about it". I'm somewhat serious about this -- we have been studying new users' rate of understanding the AF, and I catalog the kinds of questions people ask. My observation si that the more a new user looks under the hood for the underpinnings, the *less* he/she can understand and successfully use the AF. I think it is just detail overload causing the human equivalent of a buffer overflow.

Some users claim "oh, I need to know this stuff to understand AF" but their claim does not match what I and a few others observe when teaching... the looking under the hood causes more problems than it solves. You can understand it without looking under the hood, and you can look under the hood as a second pass. It got bad enough at one point that I seriously considered slapping a password on all the AF VIs just to stop the number of totally lost users who had "blinded" themselves looking into the matter. Hattip to Douglas Adams: Sure, you could in theory learn everything by looking into the Total Perspective Vortex, but more likely it will just fry your circuits. 🙂

If you happen to be someone who really can take in all those details at once, great, but I encourage you to go slowly if you aren't already well versed in asynchronous programming models.

[AristosQueue (NI)]

Amiri wrote:

Something else that confuses me is how do I differentiate the items in the Actor Framework.lvlib that I use to build my messages and stuff from the things that are under the hood, things I shouldn't see, or be looking at?

                   

Now THIS is a good question. 🙂

The short answer is that I would advise a new user should

For new AF users:

• If it ships with LabVIEW, don't look at all.
• If it is autocreated by LabVIEW, only look at it if LV leaves the block diagram open after doing the scripting (as of LV 2015 we close the message VIs).

To put it another way:

a) Only investigate the member VIs of your own actor class, either the ones you write or the ones you create by choosing "New >> VI For Override..."

b) Don't open any of the message class VIs. Only use them.

For experienced AF users:

Explore the depths. Spelunking is good for the mind and for the health of the framework!

[Amiri]

Thanks for all of the great details Brainstorms, I appreciate it.  It is all slowing starting to come together for me.  I always enjoy finally having that "Eureka!" moment; I've had small bursts of epiphanies but not the Aha! moment I'm still working on and waiting for.

[Brainstorms]

It will come to you...   And your world will never be the same afterwards. 

[Rafal_Kor]

i know beggars can't be choosers nor demand more since you've provided the tutorial in the spirit of public service, but when do you think you'll have this tutorial re-done for zero-coupled messages?

One other question, in this tutorial all the nested actors get launched/stopped simulaneouly, it that always the case in AF?or is there a way to launch/stop nested actors at will throughout application?

[Amiri]

AristosQueue wrote:

The correct answer probably should be "magic happens, don't worry about it". I'm somewhat serious about this -- we have been studying new users' rate of understanding the AF, and I catalog the kinds of questions people ask. My observation si that the more a new user looks under the hood for the underpinnings, the *less* he/she can understand and successfully use the AF. I think it is just detail overload causing the human equivalent of a buffer overflow.

                   

I agree with you, because I have heard you say the same thing in the past and so I did not want to get into the details under the hood at this time.  The *only* reason I decided to peak is because of the Do.vi magic. To me, not understanding that portion felt sort of crippling, or limiting. It's not too difficult to follow a regular queue, or dynamic event, etc. across processes, but I could not (still can't totally to be honest) follow how the Do.vi (among other things) is working exactly (Brainstorms explanation helped out a lot).  Yes, for now, I will work on just using the technology and slowly get to the point where I understand the why. Note to self, “Don’t Panic.” 😉

At some point, I feel like every developer should understand the why and how (at least to a certain extent) of what is exposed to them, if they're using "it" extensively and at this time the whole AF library is open, but I promise, I will close those BD's and stop looking!

You talked about the idea of locking things down...in the future, would it make sense that parts of the AF library would become native functions/primitives in the LV palette?

We currently use JKI's state machine and their Module Template (for interprocess comm.; dynamic events) to do what we need to do and run a bunch of parallel processes and so I know enough to be dangerous.

I like how you and Allen compared the AF to a "regular" state machine, but I would love to see a video showing even more of that detail... e.g."in your old state machine it looks like this, but now when we create this actor/message...it replaces this thingy in your old SM." And do that for everything, step by step. That is how OOP finally clicked for me, I had to keep staring at these examples where there were two solutions, one without OOP and the second one with and as I kept comparing them, it eventually clicked for me, but this wasn't in a day or two, even after taking the class.  I'm so used to the usual paradigm (state machine) it can be difficult to see this new way.  Just how an AF solution looks on the BD is very different and kinda foreign (to me).

[Brainstorms]

Amiri, the only AF VI you would ever need to peek into is "Actor Core.vi".  It's very simple, and this is where the "magic" occurs.

For a reasonably good presentation of how the traditional State Machine is "turned inside out" to result in Actor Framework, take a look at this presentation:

https://decibel.ni.com/content/docs/DOC-17109

It was produced for LV 2012, but is still applicable.  It would be nice if the team would spiff it up and update it with modern icons, etc.  (They could also add some more notes to show details on the transitition from TSM to AF.)

-t

[Amiri]

Thanks, yes I have this presentation handy and refer to it at times.  I agree, it should be spruced up a bit.

[Amiri]

Radical_Raf wrote:

One other question, in this tutorial all the nested actors get launched/stopped simulaneouly, it that always the case in AF?or is there a way to launch/stop nested actors at will throughout application?

                   

If you go to the hands on AF example here: https://decibel.ni.com/content/docs/DOC-23893;

I think the Simple Actor Example does that.  In the example they launch/stop actors at will and through user selection.

I'm going through this hands-on tutorial now...

[AristosQueue (NI)]

Amiri wrote:

You talked about the idea of locking things down...in the future, would it make sense that parts of the AF library would become native functions/primitives in the LV palette?

Our working theory is "probably not." We say probably because you never know, but, in general, we have reached a point with our compiler where writing the code in G can achieve the same efficiency as teaching the compiler new assembly for a given function. The only reason we would have to add a new primtive is if it *can't* be done in G, not if it can be done but is inefficient.

The primary thing that might drive it to become more built in is if we made actors part of the language in such a way that the framework was generated by the compiler -- i.e, the message handling loop itself was not a single fixed VI but actually had differences in behavior depending upon the target that code is being generated for or compiler-detected aspects of each individual actor class or something like that. My current thought is that we would still have an actor framework even in that case, but users would see it only indirectly because it would be obscured by an editor layer that sat in front of it to provide a better debug experience... for example, right now you drop the Call Parent Node on Actor Core to be able to run the message loop. We might reach a point where you just write your Actor Core and the call to the parent node is assumed by the editor and at run time, the parent loop is just inlined into your diagram so you can watch them all together and they breakpoint as a single unit. These are the ideas I've been brainstorming over, both here and with indivdual users in various places.

[AristosQueue (NI)]

Also, the shipping project template for the Evaporative Cooler shows dynamically starting and stopping actors with the Dual Fans -- one fan gets stopped because of a hardware fault, and the other spins up in its place. The first stops without shutting down the whole system.

[justACS]

I don't see the AF class being offered on line any time soon.

The course should get a part number sometime early next year.  We don't anticipate putting it into the rotation of regularly offered classes, but you should be able to schedule one with your local sales engineer.

[Amiri]

AristosQueue,

I'm sure you have been asked before...would you recommend converting an existing program/platform over to AF?  Why or why not?  If you would recommend it, how proficient would you recommend someone be with AF before attempting that type of a conversion and where/how would you start the process?  Any suggestions and details appreciated.

[justACS]

I'm going to weigh in on this one.

This is a difficult question, and highly dependent on your application and your future needs.

Porting working code is always a big deal, and you need to weigh the costs/benefits of conversion.  It will cost you some number of man-hours to port the code, proportional to and a significant fraction of your initial investment.  So the question becomes:  what do you hope to gain?  If you are in maintenance, it probably isn't worth the effort.  If it's an ongoing program with years left for development, then it may be worth it. 

Your primary gains would be better opportunities for reuse and extension.  If you anticipate a lot of either (you have code modules that are worth using in the next application, or you know you are going to have to repeatedly extend what you have), then it may be worth it.  Doubly so if you need to extend an application that is about to collapse under its own weight.  (i.e. how bad is your current code base?)

Actor Framework isn't all-or-nothing.  It is possible to have AF actors in a non-AF space.  You do some extra work to write shim code.  If you think AF may solve some problems for you, it's a way to get started.

I would highly recommend taking the AF class before you start the effort.  Yes, I just told you there are no plans for an on-line version.  After we get a part number for the course, you can talk to your FSE about setting up a class in your region, or even on site if you have enough people interested.

If you need help evaluating whether or not to redo an application in AF, talk to your FSE.  He can request help from support (Systems Engineering or Applications Engineering Specialists) to look at what you have and help you decide.  There is an approval process (because we are a limited resource), but we like to help where we can.

[Amiri]

Thanks niACS for the feedback.  I would like to take the class sometime in the future if possible.

[AristosQueue (NI)]

Amiri wrote:

I'm sure you have been asked before...would you recommend converting an existing program/platform over to AF? 

                   

There are programs I would recommend converting. There are others I would not. It is highly dependent upon the program in question. The primary question for me is scale -- how hard is it to maintain your current app and how much harder do you expect it to get in the future as the app grows? Compared to *most* action-oriented apps written in LV, the AF requires more organziation and makes things more well-defined, which is the kind of discipline you may be lacking if your current system is becoming unmaintainable.

[DMurrayIRL]

Apologies for the delay- The best I can promise is that I *may* have a "sequel" before the Christmas break. It's a trickier program to write. Also, if I do it in LV2015, I need to decide whether to use the new automated message creation methods, or to use the bare-bones approach of manually creating abstract messages. For consistency I should use the bare-bones approach.

[RaymondFarmer]

Hi,

I am running LabVIEW 2011 SP1 and have Actor Framework 4.1.0.29 installed. There doesn't appear to be a later version of Actor Framework for LabVIEW 2011 SP1.

I have run through the Add -Multiply Actor Project Tutorial and the final app runs and gives the right answers. The only problem is the Addition and Multiplication object are still running when I close the project down and exit labVIEW.

I suspect its something to do with the lack of 'Launch Root Actor.vi' and 'Launch Nested Actor.vi' in the version of Actor Framework I am using.

Any suggestion would be gratefully received.

Regards

Ray Farmer

[CQ_Li]

Hi,

what you need is to add stop actor functions for addition and multiplication actors when you stopped the calculator actor.

regards

[RaymondFarmer]

Hi CQ_Li,

I have added a couple of Send Normal Stop.VI in the "Stop":Value Change event and also the panel close.

That does fix my problem Thanks.

[MSteiner]

After having read quite a bunch of documents about Actor Framework, been through some LVOOP experimentations, I was looking for such a step-by-step document in order to relink theroy and practice. A good step-by-step document. Thanks a lot

[DMurrayIRL]

Thanks for the feedback, glad the document is useful.