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.

 

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.

Comments
Active Participant justACS
Active Participant

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.

Active Participant justACS
Active Participant

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.

Active Participant Oli_Wachno Active Participant
Active Participant

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

Join the Community!

GCentral
Active Participant justACS
Active Participant

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

Active Participant Oli_Wachno Active Participant
Active Participant

Thanks!

Join the Community!

GCentral
Member Noriker
Member

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.

Proven Zealot
Proven Zealot

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...

 

Proven Zealot
Proven Zealot

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.

Member Noriker
Member

Hi 

 

Proven Zealot
Proven Zealot

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Active Participant justACS
Active Participant

> 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).

Member Noriker
Member

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

Active Participant justACS
Active Participant

> 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.

Member Noriker
Member

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?

Proven Zealot
Proven Zealot

@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.

Member Noriker
Member

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

Active Participant drjdpowell Active Participant
Active Participant

> 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.

Proven Zealot
Proven Zealot

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.

Member Noriker
Member

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? 

Active Participant drjdpowell Active Participant
Active Participant

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

Member SHowell-HAL
Member

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
Contributors