topic Re: Community Nugget 4/08/2007 Action Engines in LabVIEW

Community Nugget 4/08/2007 Action Engines

Ben — Sun, 08 Apr 2007 13:37:24 GMT

Action Engines, What are They?

“An action engine is Ben's term for a functional global which includes extra actions other than just holding the data.”

(tst , 03-13-2007 01:18 PM)

In a nut shell tst has nailed it except for the “Ben’s term” part. I was originally exposed to the term "Action Engine"

by reading the book ""LabVIEW Applications Development A Course on Advanced LabVIEW Programming Techniques*”. But

before I get into details of the Action Engine (AE), I will attempt to clarify some terminology.

Functional Globals
Functional Globals (FG) are VIs that are functionally equivalent to LabVIEW globals. Functional Globals store

information. You can read them or write them and that is it. No fancy stuff. Functional Globals are also referred to as

LV2 globals because LV2 did not have globals but it did support Un-initialized Shift Registers (USRs). The USR is the

entity that stores the information.

USR.jpg

USR’s
Shift Registers (SR) come in two varieties “Initialized” and “un-initialized”. The presence or absence of a wire

feeding the SR from outside the loop distinguishes how LabVIEW will implement the SR. If there is NO wire feeding a

shift register (A), then the SR is not initialized. This is called an “Un-Initialized Shift Register”. The USR variety

is implemented as static buffer that is re-used from call to call. The values written to the USR in and earlier call

persist for access (B) in latter calls**. A Functional Global exploits this behavior by implementing two methods of

interacting with the contents of the USR.

Functional Global.JPG

In the “Write” action (not shown) the value of “Numeric in” is placed in the USR. In the “Read” action the contents of

the USR are returned via Numeric out.

Action Engines
An Action Engine (AE) can be thought of as a machine (Engine) that performs some useful task (action) often on

something (typically but not limited to data in a USR). Functional Globals are very specific type of Action Engine.

They have two actions “Write” and “Read”. They operate on the data stored in the USR either by replacing or using the

contents of the USR. So AE’s are a superset of Functional Globals. In many documents the terms AE and FG are

interchangeable. A recent poll on LAVA has indicated that Functional Global is the most popular term. Since this Nugget

was prompted by answering the question “what is an AE?” in the remainder of this document you will find that I will

generally use the term AE.

Do What to What?
AE design revolves around the ways the shared resource must be accessed manipulated or monitored. In a Functional

Global, the actions “Write” and “Read” are appropriate. That is not necessarily the case for AEs. AEs can have entirely

different set of actions depending on the interaction requirements for the information stored in the USR. A short list

follows.

A Configuration AE could allow for multiple processes to share a single copy of the system configuration (in a USR) by

providing actions like “Set Device ID”, Set Device ON-Line…

A hardware device can be realized as an AE that presents actions appropriate to the physical phenomenon being measured

or controlled.

A DO Port Controller AE could store a reference to the physical device in one SR and the port status in another SR and

have action like: Set Main Motor On”, “E-Stop”, …

An Instrument can be implemented to store the device name and settings with actions like “Set Input ON” “Auto-Scale Y”

and “Get Trace”,…

Screen Stacks can be implemented by using control references in one USR and maintain a screen view stack in another

then implementing actions like “Set Config Screen”, “Set Login Screen”, “Back”…

Users can be managed using an AE with action such as “Add New User” “Set Password”, “Disable User”…

The list goes on and is limited only by our imagination. Here is an example that shows how a running average can be

maintained.

Running_Average_Example.jpg

Running Average Example

The Running Average Example shown above shows how a running average can be maintained using an AE. The AE is

initialized before the While Loop executes. On each iteration of the loop the simulated measurement value (random

number) is used to update the history of all measurements (Add Number(s)) and the mean is calculated (Calc Mean).

Please note that although the buffer of all measurements is affected in every step of this example, the buffer (USR in

the sub-VI) contents are never part of this VI’s diagram. Since the history is stored in the sub-VI, the history can be

acted on from more than one thread as shown below.

Parallel_Loops.jpg

In the parallel Loops Example the history is initialized and then two loops run in parallel with one updating the

history and the other plotting the average. Since the History resides inside the USR of the sub-VI the two while loops

are effectively sharing the same block of memory, the block used to store the USR. The Sub-VI was implemented as shown

in the following sequence of images.

Init.jpg

As was the case with Functional Globals, the actions are implemented as a type def’d enum***** driven case structure.

Appropriate code is present in each case to realize the intended actions. In the “Init” case, contents of “Array in”

are used to initialize the history. In our example above we did not pass an initial array value. Therefore the “Init”

resets the history (cleared the array).

Add Num.JPG

The operation of the AE when the “Add Number(s)” action is called varies depending on its usage. If the caller passes a

non-empty array, it is appended to the array. Alternatively, passing a value via the Numeric in” control, and leaving

the “Array in” un-wired adds a single element to the history. We used the Numeric In input so we were continually

building our history one value at a time.

Calc_Mean.JPG

When the “Calc Mean” action is invoked, the average is calculated and returned.

This Nugget is continued in the next post

Re: Community Nugget 4/08/2007 Action Engines

Ben — Sun, 08 Apr 2007 13:58:16 GMT

Nugget continued

The Traffic Cop Behind the Scenes
A detail I have not mentioned up until now is that AEs should be implemented as VIs that are not reentrant***. VIs that are not reentrant can only be executing in one context at a time. LabVIEW will ensure that if there is ever a situation were two contexts are attempting to act on the same AE at the same time, LabVIEW will schedule the first and the subsequent will wait until the first call completes. This is similar to a traffic cop preventing more than one vehicle from entering an intersection at the same time. The Traffic Cop is illustrated in the following timing diagram were we look at how the processing of two threads is affected by using a single AE.

Execution_Timeline.JPG

In the figure above the processing time of two processes “P1” and “P2” are illustrated by a red or blue solid arrow respectively. In the parallel loops example shown earlier, P1 could be the “Calc Mean” loop and P2 could be the “Add Number(s)” loop.

t0 - t1
Both processes are executable and run their assigned tasks. Neither process is accessing the AE.

t1 – t2
P2 continues to run while P1 calls the AE. Since the AE is idle it is available to run so P1 continues execution running inside the AE until all work inside the AE completes. The dotted arrow shows that the thread for P1 is executing in the data space allocated for the AE.

t2 –t3
At t2 the AE terminates and both process run as in t0 – t1.

t3 – t4
This time segment is similar to t1 – t2 with P2 running in the AE.

t4 – t5
Similar to t2 – t3 the AE terminates and both process run.

t5 – t6
Similar to t1 – t2. P1 take control of the AE.

t6 - t7
At t6 P2 attempts to call the AE. Since the AE is not idle it is not available to run. P2 is placed in a resource wait state (it is NOT running) waiting for the resource to become available. The dotted horizontal arrow indicates the process is not executing.

t7 –t8
At t7 the call of the AE by P1 that started at t5 completes and P1 continues to execute outside of the AE. When the call by P1 completes the AE becomes available. The process P2 is marked as executable. The scheduler includes P2 in its executable threads and the AE is available. P2 then executes inside the AE until the call completes.

The Beauty of the AE
This behavior of a non-reentrant VI is a wonderful feature we can exploit to eliminate race conditions. Race conditions are the nemesis of many a developer. In hardware this was solved with clocked enabled logic. In LV we solve race conditions with Queues, Semaphores, Rendezvous, Occurrences, and Action Engines!AEs can eliminate race conditions when all operations involving updates of the data stored in the USR are done INSIDE the AE. A very simple illustration of how the encapsulation of USR manipulation is shown in the following set of examples.

Port_With_Global.jpg

This VI is intended to demonstrate how two bits of an eight-bit port can be used to control the running state of two pumps. To illustrate the control process, one pump will be set running at start-up and then every half second the state of both pumps will be toggled to simulate switching of the supply. This example uses globals and fails miserably.

Port_With_Global.jpg

In this example we start out by initializing a global variable so that bit “1” (zero based) is the only bit set in an array of eight bits. This turns on Pump 2 to start. Then the “Port Update” and a “State Change” loops run in parallel. In the “Port Update” loop the state of the port is read from the global and used to update the GUI.

In the “State Change” loop, the port status is read and the first Boolean is inverted before being written back to the global. Similarly for the second Boolean. Since the read of the globals both occur before the subsequent data processing, one of the threads will be processing old data.

Port_With_Action_Engine.jpg

The Action Engine version codes up the same way as the global version but now all of the data manipulation of the port states are encapsulated in the Action Engine “Port Controller”. This encapsulation ensures all operations involving the data in the USR are forced to happen sequentially even though we did not have to implement any code to achieve this affect.

The key point to take away from this example is a shared resource (the port status in the case) when implemented as AEs come with resource contention resolution built in provided that all manipulation of the shared resource takes place inside the AE.

Action Engines to the rescue!
Action Engines are not a replacement for Queues, Rendezvous and the other synchronization techniques. They are typically called for when your design dictates that a single resource must be shared by more than one parallel process and none of the LabVIEW provided techniques are sufficient. They require a design of their own to ensure they work correctly. They also have to be developed and supported.

This Nugget is continued in the next post

Re: Community Nugget 4/08/2007 Action Engines

Ben — Sun, 08 Apr 2007 13:58:38 GMT

Wrapping It Up
After submitting this Nugget for review by my fellow Champions, Jim Kring mentioned that he wraps up his AE calls in sub-VIs. This is a wonderful way of solving two challenges associated with AE use. The first challenge is not being able to set important inputs to the AE as “Required”.

If we develop a wrapper VI for each type of AE call, we can designate all of the required inputs for proper operation of the AE function call as “Required”. Without using the wrapper VI to ensure the proper calling convention, the inputs required for ANY AE function would be required ALL AE calls.

Example. Suppose you have an AE that stores all of the user information in your application. Among other functions the AE includes the actions “Set User Password’ and “List all Users”. Since a “User Name” input is required for setting a users password correctly, this input would be required when attempting to get a list of all of the user with the “List all Users” action. By wrapping up the individual actions in appropriate wrapper Vis, we can set the “User Name” input as required in the “Set User Password” wrapper. The “List all Users” wrapper would not have a “User Name” input.

A second benefit of using a wrapper VI for each action of the AE is in making maintenance easier. Since each type of access to the AE is encapsulated its own VI, a search for a selected wrapper VI is a search for all actions of that type. If you know there is only one type of action that can cause a condition you are trying to modify, you can quickly find all of the code that can be affected by changes to that action.

Closing Notes
1) When using your AE remember the data is in the USR.
2) Let your data define your actions
3) Avoid super clusters
4) Hierarchies of AEs help keep your data structures simpler
5) Self initializing and recursive AE are both elegant and efficient
6) AEs do not require a While Loop.

Questions
7) Do you have a process that you go through when designing AEs, what is it?
😎 Does anyone use the techniques used for Normalizing Databases to AE design?
9) Do you think that a USR is required for a VI to be considered an AE, e.g. "Could use a dll call and still call it a AE?"

If you have a Nugget you would like to present please post here to reserve your week!

A list of all Nuggets can be found here.

I want to offer thanks to Albert Gevens and Jim Kring for their assistance in creating this Nugget.

Ben

Foot Notes
*LabVIEW Programming Techniques" produced by Viewpoint Systems Version 2.2 August, 2000 page 67. I believe this book was the precursor to the original version of NI’s "Advanced Applications Development Course"

**An Action Engine is generally implemented as a VI that is not reentrant to share the USR across multiple instances of the sub-VI. A reentrant VI will allocate a unique data space for each instance of the VI.

***Come on Ben can’t you go a couple of Nuggets with out bringing up reentrancy? Nope.

**** A “Race condition” is a term used to describe the situation were information from different sources are not consistent with each other. This term originated in the hardware of computers were address and control signals could arrive at the inputs of chips at different times resulting in the new control state applying to the old address (for example). In LabVIEW this condition exists whenever there are two writers of an object (Global, Local, etc) that are executing at the same time.

***** Please see the previous Nugget “Type Definitions Let You See Your Application in a Different Way” found here .
Type def’d enums are highly recommended for AE development because the case structures cases will adapt to the enum changes when the type def’s are changed. When you use enums it is prudent to give some thought to how you want you AE to respond to new actions being added. If your AE has a action which is not destructive, e.g. “Read” you can assign it as the default action allowing new action s to be added without changes to the AE. If every action requires a developer’s attention, then do NOT define a default action. The AE will break until all of the actions are accounted for by the case structure.

Message Edited by Ben on 04-08-2007 09:01 AM

Re: Community Nugget 4/08/2007 Action Engines

Tomi_Maila — Sun, 08 Apr 2007 15:06:14 GMT

Wow Ben,

This is the longest nugget I've ever read. I take my time to read trough it but I'm already sure it's good.

Thank you Ben!

EDIT: I think you raise an important question about access to shared resources and how action engines help to deal with access to shared resources. This issue becomes especially important when using shared resources in LabVIEW object oriented programming. If one wants to implement a class level variable similar to C++ or Java static variables, one needs to control the access to this variable somehow to avoid race conditions. Locking a class level variable is not an option as every single object of that specifc class gets locked up. Action engines come in help here as they allow encapsulating action together with a shared resource. So instead of using shared class level variables in LabVIEW object oriented programming, I recommed using class level action engines.

I won't go in to detail on this issue now. I'll be writing an article series Introduction to LabVIEW object-oriented programming at my blog EXPRESSIONFLOW (expressionflow.com). This action engine shared class-level resources is an issue I will raise up in this series later on when I've covered enough basics so that this issue is clear for the readers. Subscribe to the RSS feed not to miss it.

Tomi

Message Edited by Tomi M on 04-08-2007 06:26 PM

Re: Community Nugget 4/08/2007 Action Engines

altenbach — Sun, 08 Apr 2007 15:46:54 GMT

Great Nugget. I love the term "action engine".

Some minor comments.

(1) One performance related item is worth pointing out because new users might be tempted to do things wrong:

It has been discussed very long ago that it apparently makes a significant performance difference, depending if the terminals of a subVI are placed inside or outside the structures. "Outside" is better and the given examples are correct in this respect!

For example, some might be tempted to place the "Numeric in" and "Array in" terminals inside the "add Numbers" case because they are not really used in the other cases. Similarly, the "Numeric out" could be placed inside the "mean" case, because it is the only case that produces meaningful (sic) results for it. These design changes will probably produce an undesirable performance hit.

(2) Some LabVIEW zealots (not necessarily a bad thing) might also point out that the "array out" is useless because it simply duplicates whatever input arrives at "array in". In this case it makes no sense to even have that output. Also the "Numeric out" should be renamed to "mean out" and should produce e.g. NaN in all actions except "calculate mean".

(3) I don't see a problem with the mean of a single number, it gives a well defined result. We only have a problem if the array size is zero, in which case we should produce a NaN. This happens automatically so no extra code is needed.

(4) let's also not forget the "first call?" function. Sometimes it can be used to design a self initializing action engine.

Re: Community Nugget 4/08/2007 Action Engines

AristosQueue (NI) — Sun, 08 Apr 2007 16:31:45 GMT

If you're interested in an improved functional global, you might want to see what LV's new object-oriented programming can do to the functional global.

You can download "the last functional global you'll ever have to write" from
http://jabberwocky.outriangle.org/LV2OO_Style_Global_v1.0.zip

Detailed information about the .zip file can be found on page 10 of the PDF file:
http://forums.ni.com/ni/board/message?board.id=170&message.id=216094&requireLogin=False

Message Edited by Aristos Queue on 04-08-2007 11:33 AM

Re: Community Nugget 4/08/2007 Action Engines

Tomi_Maila — Sun, 08 Apr 2007 18:07:32 GMT

(2) Some LabVIEW zealots (not necessarily a bad thing) might also point out that the "array out" is useless because it simply duplicates whatever input arrives at "array in". In this case it makes no sense to even have that output. Also the "Numeric out" should be renamed to "mean out" and should produce e.g. NaN in all actions except "calculate mean".

There is one case where having the array out is a good idea. It's when your array is huge and you want to be sure that no extra buffer copies of the array are made. If you duplicate the wire on the caller block-diagram then there is a risk of an extra and unnecessary buffer copy.

Re: Community Nugget 4/08/2007 Action Engines

altenbach — Mon, 09 Apr 2007 00:01:20 GMT

Tomi M wrote:
There is one case where having the array out is a good idea. It's when your array is huge and you want to be sure that no extra buffer copies of the array are made. If you duplicate the wire on the caller block-diagram then there is a risk of an extra and unnecessary buffer copy.

Are you sure about that? My gut feeling tells me that creating an unneeded output terminal cannot prevent an extra copy. Maybe somebody can make a test VI and see. 😉

Re: Community Nugget 4/08/2007 Action Engines

Jarrod_S. — Mon, 09 Apr 2007 01:16:43 GMT

The key word there is "unneeded." Notice in Tomi's post the reference to "if the user branches the array wire..." In other words, the user wants to use the array in the action engine, but also wants to use it in the top-level VI. If you pass it into the AE and keep track of it in a shift register, then the in-placeness algorithm stands a very good chance of being able to use a reference to the array in the subVI instead of making a copy. If you instead branch the wire on the top-level and don't pass the data through the AE, it's very likely LV might have to make a copy.

Re: Community Nugget 4/08/2007 Action Engines

ohiofudu — Mon, 09 Apr 2007 10:44:27 GMT

Good Ben,
Thank you so munch for this Nugget this is the best one I have seen so far in this community.Thanks once again.

CLAD

Re: Community Nugget 4/08/2007 Action Engines

Ben — Mon, 09 Apr 2007 11:07:01 GMT

Well it looks like my concern about addinga section on performance was un justified.

Thank you for point out the placement of control and how they affect the performance.

Others have touched on the idea of passing an array through a VI (hopefully by reference) to allow the buffer to be "inspected" by the sub-VI. After the sub-VI completes another function can use the same buffer.

Christian wrote;

Also the "Numeric out" should be renamed to "mean out" and should produce e.g. NaN in all actions except "calculate mean".

Good point! ...

unless the AE also offers a "Min" and "Max" function (which this examples does not).

Ben

Re: Community Nugget 4/08/2007 Action Engines

Matthew_Williams — Mon, 09 Apr 2007 12:28:36 GMT

Bravo, Ben! Very nice. Thanks.

Matt

Re: Community Nugget 4/08/2007 Action Engines

Kevin_Price — Mon, 09 Apr 2007 12:34:45 GMT

Very nicely-done nugget! FG's and AE's are *very* useful constructs indeed.

Most of my apps involve heavy doses of data acq and I almost always implement an AE around each data acq task (or small set of closely-coupled tasks). This sets me up with 1 common interface to each logical unit of hardware. It has proved to be a pretty effective strategy for re-use as well. The data acq tasks naturally turn into pretty self-contained modules needing relatively little modification from app to app. (Sometimes none at all.)

Like altenbach mentioned, I also almost always use the "First Call?" primitive in any FG to guarantee some kind of initialization. Typically, if the first call performs a "Read" action, I'll catch that fact and provide sensible initialization values. Depending on the FG in question, I may just pass through the default inputs, or I may use special values like NaN, "<undefined>" enum values, or even assert the error cluster -- depending on how crucial it is to have initialized *explicitly*.

-Kevin P.

Re: Community Nugget 4/08/2007 Action Engines

johnsold — Mon, 09 Apr 2007 13:13:58 GMT

Some of my early (~LV3) functional globals (had not heard the term Action Engine then) had a Valid output. It remained False until a Write had occurred and was reset to False if the Reset action was performed.

Nice job, Ben.

Lynn

Re: Community Nugget 4/08/2007 Action Engines

DFGray — Mon, 09 Apr 2007 13:19:44 GMT

Nice job, Ben. I have one more performance improvement that only is worth considering if you are using the AE to store a dynamic array and you are adding data to or subtracting data from the array frequently. It results in code which is quite a bit more complex.

Build array is a very expensive operation due to using the memory manager and, if used repeatedly, can fragment memory, causing more performance issues. You need to create some sort of memory management so you don't keep hitting the build array primitive, and the AE allows you to do this. The executive summary - when you initialize the array, always create twice as many data points as you need, and a minimum of 8 to 16 points. Keep track of the number of points actually used and the number available. When you add points to the array, if you need more space, double the array size. If you subtract data from the array, halve the size if you get to less than one quarter of the points actually used. Note that actual increases and decreases should be tweaked for your application. Operations such as min, max, and average may be more efficiently done when points are added (although that is a performance issue each application will need to work out).

If I have a chance, I will code it up and post it. I have used this in the past with dramatically better performance, but details count, and any particular problem may or may not benefit from such an approach. The time you save adding points may be lost when processing them, since you cannot use the array operations without creating a subset of the array, which hits the memory manager and may cause a copy. The best way around this issue is processing the points as you add them, but you can easily end up losing any performance gain you got by not hitting the memory manager. Of course, you sort of get the performance back on the read, since the values already exist.

Your mileage may vary...

Re: Community Nugget 4/08/2007 Action Engines

Ben — Mon, 09 Apr 2007 14:14:13 GMT

Hi All,

I will try to reply to the replies in chronological order as time permits.

Tomi,

Now that this Nugget is out of my head I will look into harnessing the LVOOP ideas you have been pushing. I'll reply back with this.

Aristos,

I WILL have to follow-up on your link. Concidering how much time I spend with AE's your comments are very tempting!

I will reply to the other posting when I get a break.

Thank you!

Ben

Re: Community Nugget 4/08/2007 Action Engines

Ben — Mon, 09 Apr 2007 15:52:26 GMT

Tomi Stephan and others,

To get my head around how to think LVOOPishly, I appreciate a little help.

In my Action Engines...

Should I understand the data in the USR to be a class or is the cluster that defines the USR contents that I should think of as a "Class"?

If I perform an action that modifies the USR, is that a "method"?

If I just read out the "average" is that a "property"?

Ben

Re: Community Nugget 4/08/2007 Action Engines

Matthew_Williams — Mon, 09 Apr 2007 15:56:31 GMT

To follow up on DFGray's comments, I usually keep a pointer (in the AE) to the next available location in the AE array.
When the pointer = array size, time to go get more array elements. If you allocate in 100 entry chunks your memory
manager overhead is decreased by ~99%, with modest over-allocation. Works very well for typical AE array sizes we
work with, hundreds to low tens-of-thousands elements.

Matt

Re: Community Nugget 4/08/2007 Action Engines

Jarrod_S. — Mon, 09 Apr 2007 16:48:03 GMT

It seems to me the entire FG would constitute a class, since a class is not only stored data but the functions that operate on that data. The cluster in the USR is your private data, since it obviously can't be accessed outside the FG without accessor methods.

Reading a property would simply be outputting a data value that is stored in the USRs. This could include one element out of a cluster. If you are storing your average in the USR and you just want to output it without recalculating it, then yes, that could be a property. If you include the act of calculating it, that sounds more like a method.

The analogy with LV2-style Functional Globals and classes seems to break down when you start talking about inheritance, because there's no automatic way to inherit a FG and get all its data and methods along with your own new child data and methods. You would have to modify the original functional global to extend its functionality in such a way.

Re: Community Nugget 4/08/2007 Action Engines

Tomi_Maila — Mon, 09 Apr 2007 17:05:45 GMT

Should I understand the data in the USR to be a class or is the cluster that defines the USR contents that I should think of as a "Class"?

I haven't had time to take a look for Stephens example so I will not talk for Stephen but only for myself. The USR could be but would not neet to be an object in LabVOOP. It can as well be anything else such like in pre-LabVOOP LabVIEW. The more relevant question is if the USR containst the class type the VI (method) belongs to or something else. However the story is too long to be replied here wihtout much too many references to undefined issues. I'd rather go on my introduction to LabVIEW object-oriented programming in my blog at expressionflow. When the time is right I'll talk about functional globals and action engines in contexto of object-oriented programming.

My advice, it's very hard to wrap you head around object-oriented programming without actually reading something. The easiest way would be to follow my blog for some time. The more challenging way would be to read one or more books on OOP in the context of some other programming language such as Java.

Tomi