Actor Framework Documents

cancel
Showing results for 
Search instead for 
Did you mean: 

Network Endpoint Actors

Network Endpoints allow you to link two actors running in separate application instances.

 

Update (8/24/21):  Version 3.0 has been released!  Get it from the NI Tools Network repository in VI Package Manager.  See below for release notes.

I am working on version 4.0, which will take advantage of interfaces.

 

Network Endpoints manage a Message Stream.  Message Stream is an abstract class that defines an API for transmitting Actor Framework messages between applications.  Children of this class adapt specific protocols, like TCP/IP or Network Streams to the API.  Message Streams will transmit and receive any message class.  Message Streams are described in more detail later in this document.

 

Use Write Message Stream.vi to specify the Message Stream that will be used for the connection.  You must set this value prior to launching the actor.

 

Network Endpoint is an abstract class.  Use Nested Endpoint or Caller Endpoint in applications.

To use a network endpoint (Caller or Nested), place an endpoint constant on the block diagram. Use Write Message Stream.vi to set the instance of Message Stream to use for the session.  Launch the network endpoint.  The endpoint will attempt to connect to its remote counterpart.  If the connection times out, the launch attempt will fail.  If connection is established, the endpoint will run until it receives a Stop message; it will break the network connection and return Last Ack to its caller.  An endpoint will also stop automatically if its remote connection is broken.

 

Use Write timeout.vi to set the amount of time the actor will wait while attempting to create an endpoint (i.e. while waiting for a connection). If this value is too small, you may experience difficulty obtaining a connection.  If it is too large, you may observe a delay when attempting to stop the actor.  You must set this value prior to launching the actor.

 

Network Endpoints have no message classes of their own; you can send any message class to an endpoint. Stop and Last Ack are handled locally; anything else is forwarded to the remote endpoint.

 

Nested Endpoints

 

A Nested Endpoint is a Network Endpoint that is launched by a calling actor.  The nested endpoint will forward messages it receives from its caller across the network.    Any message the nested endpoint receives from across the network will be passed up to its caller.

 

When used with a remote nested endpoint, the endpoints establish a sibling relationship between the actors.

 

When used with a remote Caller Endpoint, the endpoints establish a caller-nested relationship between the actors.

 

Nested Endpoints send a Connected Msg to their callers when they successfully connect to a remote endpoint (of any type).   Connected messages are abstract; the caller must provide the actual implementation to be used.  The payload of a Connected message is the nested endpoint’s enqueuer; use this data when you are using multiple nested endpoints, and need to identify which endpoint has successfully connected.

 

Use Write Connected Msg.vi to set a concrete implementation of Connected Msg to send to the caller.

 

Caller Endpoints

 

A Caller Endpoint is a Network Endpoint that sits at the top of an actor tree.  Caller endpoints launch a single nested actor that you specify. If a remote actor uses a nested endpoint to connect to a local caller endpoint, the caller endpoint's nested actor will act like a nested actor of the remote actor.  Any messages sent from the nested actor to its caller will be forwarded across the network connection.  Any messages received from across the network by the caller endpoint will be passed down to the nested actor.

 

If Caller Endpoint receives a Last Ack from its nested actor, it will forward the Last Ack across the network.  Note that, due to restrictions in the Actor Framework API, the priority of the Last Ack message will be downgraded from Critical to High.  The Caller Endpoint will remain active; it is the responsibility of the calling application to destroy it.

 

Very little work has been done with Caller Endpoints, and they should be considered experimental.

 

Use Read/Write Nested Actor.vi to get or set the nested actor called by the Caller Endpoint.

 

Message Streams

 

Message Streams transmit Actor Framework messages between applications.  Children of the class implement specific protocols.  Message Streams for TCP/IP and Network Streams are included in the Network Endpoint Actors package.

 

The API requires that one endpoint be the initiator, and the other the listener. To reflect this, each protocol is implemented as a pair of classes, Initiator and Listener.  Passing an instance of TCP Stream Initiator to a network endpoint means the endpoint will attempt to connect to another endpoint. Passing an instance of TCP Stream Listener to a network endpoint means the endpoint will wait passively for a connection.  In either case, if no connection is made within the timeout period, the endpoint will shut down and return an error.

 

Both Initiator and Listener classes include a Create method.  Create methods take address information as inputs, and return a Message Stream object.

 

Message Streams can accept a Cipher plug-in, which you can use to encrypt/decrypt transmitted messages. Cipher is an abstract class; inherit from this class to add specific ciphers to your application.  No ciphers are included in the Network Endpoint Actors package.

 

How Network Endpoint Actors Differ from the Linked Network Actor

 

Network endpoints do not persist between connections, meaning that a network endpoint actor will stop itself if it fails to connect to a remote endpoint, or if the remote endpoint ends the connection.  Linked network actors persist between connections - when the remote disconnects, the LNA will wait for a new connection.  It should be a straightforward task to build a version of the Linked Network Actor that uses network endpoints; such an implementation would better adhere to the Single Responsibility Principle.

 

LNAs currently only support network streams, whereas network endpoints can also use TCP/IP, or any other protocol you wish to implement.  Network streams also have some support for encryption extensions.

 

Finally, LNAs require you to do extra work to package a message for transmission, i.e. you have to send your message to the LNA for forwarding via a Transmit Message.  Network endpoints make use of an override of the Receive Message.vi method to make transmission transparent.

 

As with LNAs, you will need to wrap your network endpoints in some form of proxy class to manage library locking.

 

About the Packages

 

The latest version of the Network Endpoint Actors is available on VIPM.

 

vipm://national_instruments_lib_ni_network_endpoint_actors

 

The attached files below are VI Package Configurations, and include the base package and an example.  The versions are nearly identical, except that the 2015 version includes DETT (Desktop Execution Trace Toolkit) support.

 

Update (1/7/16):  Many of you want to use Network Endpoints to create client-server architectures, where the remote client is only intermittently connected.  Since the endpoints are single-use (the actors stop when you break the connection), several people have enquired about the best way to restart the server-side endpoint.  Here is the simplest way to have your server detect that its endpoint has terminated and restart it.

 

When the server endpoint terminates, it will send its caller a Last Ack message.  Use this fact.

 

1.  In the caller, create an override of Handle Last Ack Core.vi.

2.  In Handle Last Ack Core, use the Read Actor method of Last Ack to get the nested endpoint actor.

3.  Relaunch the endpoint using Launch Nested Actor.vi

4.  Save the endpoint enqueuer for later use.

 

Here is a block diagram illustrating the concept:

Restarting an actor.png

 

Intelligent use of overrides of Handle Last Ack Core can do truly amazing things for your code.

 

Version 3.0 Release Notes:

 

This package is now licensed under the Apache License, Version 2.0.

 

I replaced (the non-reentrant) General Error Handler.vi in Network Endpoint:Receive Message.vi with (the reentrant) Clear Errors.vi

 

Users may now specify the local IP address to use with a TCP Stream Listener, which enables support for multiple NICs.

 

I have wrapped the flatten/unflatten functionality in TCP Stream Send Message.vi and Receive Message.vi in a class, called the Message Flattener. Users can override Message Flattener to support different flattening schemes.  Among other things, this is useful when sending messages to non-AF or non-LabVIEW environments.  Message Flattener also includes an override method, called Swap Endianness, to allow the user to change the Endianness of the packet size value. By default, it is little-endian, but some non-LabVIEW systems may require this value to be big-endian.

 

The packet size is now sent with a separate TCP Write, which eliminates a potentially large memory copy on the block diagram.

 

This release fixes a bug where the Register Actor message (part of the AF Debug system) was being forwarded to the remote connection. This would result in incorrect reporting in the remote's DETT traces.

 

The Register Actor message was introduced in LV 2017, hence the version bump. However, the implementation can be back ported to 2015 or 2016, if required.

 

 

Comments
justACS
Active Participant Active Participant
Active Participant
on

The package configurations have been updated for both 2014 and 2015.  These changes fix a showstopper bug with the Network Stream protocol, so I recommend you upgrade immediately if you  plan to use Network Streams.

The 2014 configuration contains Network Endpoints 1.0.0.9, with these changes:

Fixed a bug where the Network Stream Initiator was not sending its IP address toe the Listener during connect.

Fixed a bug where Network Stream Listener:Connect had an incorrect timeout (the buffer size) wired to Read Single Element from Stream.

Corrected the labels on class input/output front panel items on various methods.

The 2015 configuration contains Network Endpoints 2.0.0.11, with all the 2014 changes, plus:

Changed Netowrk Endpoint:Receive Message to use a more elegant form of message filtering, based on Preserve Run-Time Class.

justACS
Active Participant Active Participant
Active Participant
on

I have made one more change to these packages:

I fixed a bug where a communications error would stop the Endpoint as expected, but not be reported as part of Last Ack.  Errors are now reported when the Endpoint terminates.

This change affects the 2014 version (1.0.1.10) and the 2015 version (2.0.1.12).

The VIPCs have been updated.

Oli_Wachno
Active Participant Active Participant
Active Participant
on

Are there examples available? Sorry, if I've missed them

justACS
Active Participant Active Participant
Active Participant
on

The VIPC installs an example.  Once you have installed the package, open VIPM and look for "NI Nested Endpoint Actors Example".

Oli_Wachno
Active Participant Active Participant
Active Participant
on

Thanks!

Noriker
Member
Member
on

It would be helpful if there are more detailed documentations on how to use the network endpoint actors. There is also a lack of documentations for the example. It makes hard to use it. In general, NI Actor Framework is poorly documented. Please provide useful links or other resources on how to learn about NI Actor Frameworks.

AristosQueue (NI)
NI Employee (retired)
on

Noriker: The AF is one of the most heavily documented parts of all of LabVIEW. It has shipping documentation, whitepapers, videos, multiple presentations, an entire cust ed course, and a dedicated forum. You can find many of those linked on this forum's READ THIS FIRST page:

https://forums.ni.com/t5/Actor-Framework-Documents/READ-THIS-FIRST-to-get-started-with-Actor-Framewo...

 

AristosQueue (NI)
NI Employee (retired)
on

Noriker: I was trying to be helpful yesterday, but in retrospect, my reply seems to come across rather callous. Sorry about that.

I was trying to highlight the variety of documentation such that you can pick the flavor you'd like to use for learning, not trying to insult you for not having used that documentation. If none of that is helpful, please post back again.

Noriker
Member
Member
on

Hi 

 

AristosQueue (NI)
NI Employee (retired)
on

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

justACS
Active Participant Active Participant
Active Participant
on

> I strongly encourage your senior staff to take the Actor Framework customer education course. That course incorporates not > just the "what do I click on to use AF" stuff, but also the high-level design work needed to create large apps with it.

 

I strongly agree with this statement.  I teach this course, and I work with teams and individuals using AF on their projects, and I see the difference in comprehension between those who have taken the course, and those who haven't.  It's substantial.  I'd go a step further and recommend putting your entire project team through the course.  The junior membes may miss some subtleties, but they struggle less with having to unlearn practices common in other frameworks.

 

Network endpoints are actually covered in class, by the way, in a couple of different contexts (how they are used, and how they are put together).

Noriker
Member
Member
on

Unfortunately the course is not available here currently. Do you have any course material to share please?

justACS
Active Participant Active Participant
Active Participant
on

> Unfortunately the course is not available here currently.

 

There are ways to work with NI to change that.  Where are you?  How many people are on your team?

 

> Do you have any course material to share please?

 

Sadly, no.  AOD in LabVIEW course kits are not available outside of a regular or custom course setting.

Noriker
Member
Member
on

We are in Cheltenham UK, team of 3~4.

Another question: Is Actor Framework built in Labview NXG? What is the future for actor Framework in relation to Labview NXG?

Are they completely independent? What is NI's plan?

AristosQueue (NI)
NI Employee (retired)
on

@Noriker wrote:

Another question: Is Actor Framework built in Labview NXG? What is the future for actor Framework in relation to Labview NXG? Are they completely independent? What is NI's plan?


The run-time portion Actor Framework is written entirely, top to bottom, in G. There's no special NI-behind-the-scenes magic involved -- any user could have written it. That means that as soon as NXG supports all the features used by the Actor Framework, the AF itself will migrate across using the code migration tools for moving into NXG. Having said that, AF uses a lot of LabVIEW features, so it will be few versions before the AF is completely supported, but it is on the timetable.

 

That's how the AF shipped in LabVIEW 2012. But in later versions, we added editor extensions that dramatically improved the usability of the AF, such as the tools that let users quickly script message classes. That code is also written in G, but it is all scripting for today's LabVIEW. That code will not migrate. The NXG team will need to supply those tools. A timetable for that work is not established. Without those tools, the AF in NXG would be usable, but would be the same highly manual process that we had in LabVIEW 2012.

Noriker
Member
Member
on

Thanks so much for the insight. It's a great help for us to plan the future.

drjdpowell
Trusted Enthusiast Trusted Enthusiast
Trusted Enthusiast
on

> We are in Cheltenham UK, team of 3~4.

 

Hello, I’m a LabVIEW Consultant in Oxford, far commuting range from Cheltenham.  Though I don’t use the AF (I developed another actor-oriented package with Networking called Messenger Library) I am familiar with many of the available LabVIEW frameworks and could give advice on which might work best for your team and your current codebase.

AristosQueue (NI)
NI Employee (retired)
on

Noriker: Powell is a good resource to lean on. He aided the design of the AF, although he does not use it himself (different design priorities between the different messaging frameworks). Very sharp G programmer.

Noriker
Member
Member
on

Hi AristosQueue, Thanks for the notes. I have been trying to contact Dr Powell on the forum and PM. Do you know any other ways I could contact him please? 

drjdpowell
Trusted Enthusiast Trusted Enthusiast
Trusted Enthusiast
on

Hi, I've received your PM now.  I will email you.  -- James

SHowell-HAL
Member
Member
on

Hey guys, could use some help here. I have an RT application where I will be communicating with a cRIO target.

 

I have been trying all day long to get the Network Endpoint Actor library to work and cannot get it to connect no matter what I do.

 

I have created an adapter on each side so that the libraries are not locked.

 

I've tried having the initiator on both the host side and the rt side, it times out and will not connect.

I have simple names Host and RT and then put the IP address of the remote in.

On the remote side, I have listener named RT.

 

I launch the RT side first and then have it wait with no timeout waiting to have a connection. I can't tell if that VI is running because even when I check show when called it does not pop up.

When I run the launcher on the host side, it waits the timeout and then pops up -314001.

 

I opened the network streams example and placed the target VI onto the RT and then tried the example and it worked fine. It appears to be something in how the endpoint names are being created in the Network Endpoint Actor library.

 

 

Steven R. Howell
A&T Sr. Electrical Engineer

3000 N Sam Houston Pkwy E
Houston, TX 77032-3219
steven.howell@halliburton.com
felipefoz
Member Member
Member
on

Thanks for the contribution Allen, this is indeed a great tool, pulls AF to another level.

 

As I was writing here, I got back to the Kudos button, and it turns out it was the first thing I did when I was reading the update.

 

We can just give kudos once, right? why not twice?

 

norbi597@gmail.com
Member
Member
on

Hi All,

 

I think it's a shame that a NI-published package is not working. I've downloaded the latest version (v4.0.0.22) and faced the same problem as @SHowell-HAL. 
I fixed the Connect VI in the Network Listener and the Network Initiator classes. Sending the host IP address when connecting is totally unnecessary and not a good idea because it would not work if the host and the target are not on the same local network, what is more, I have more than one network card in my laptop, and it would not know which IP address to send. Anyway, I just removed the "Context" member from the classes and wired the reader and writer URLs both in the network initiator's connect VI.

There are also a few things with this package that do not look nice to me, but now I only focus on the Network stream connection.

 

Network Stream Initiator->Connect.vi

 

norbi597gmailcom_0-1687332369557.png

 

Network Stream Listener->Connect.vi

norbi597gmailcom_1-1687332447483.png

 

Regards,

 

Norbert Szilágyi

University of Szeged

Hungary

szilagyi.norbert@szte.hu

 

justACS
Active Participant Active Participant
Active Participant
on

@norbi597@gmail.com,

 

I wrote this package when I was at NI, and I continue to maintain it as a side project.  I work on it when there is a need and I have spare time.

 

Do me a favor and send me a zip file with your versions of the Initiator and Listener classes.  I'll look at incorporating your changes into a future version of the package in some fashion.  In the mean time, I can post your version to the repository as an alternate protocol option.

norbi597@gmail.com
Member
Member
on

@justACS

 

Sorry for the strong words in my comment, anyway, apart from this bug and some coding style issues, I like the concept, and the classes are well organized, so well done 🙂 

 

Here I attached my version of the package (saved in LV 2021)

 

Google Drive 

 

Enjoy!

Contributors