You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Updated documentation and the VIPM Package definition to reflect the PP work. VIPM Package built
* The Readme.md quick start section was updated to reflect the implementation of the Project Provider to create the Async Methods Actor. The quick start is now way more friendly with screenshots.
* The VIPM Package definition was updated to installe the Project Porvider Message Creator
* The v1.1.0 of the VIPM package was built and tested
- Added a "Async Message Settings" to be used by the LS AF Message Maker to create send methods for the concrete Async Messages
39
-
- Removed dependency on OpenG error and variant libraries
40
-
- Minimum LabVIEW version requirement moves from 2023 to 2020
41
-
- All the Async Message within the example were regenerated by means of the LSI AF Message Maker. The calling example code was updated accordingly</Release_Notes>
37
+
<Release_Notes>- Added a Project Provider used to to allow the user to create a new Async Method Actor from within his LabVIEW project</Release_Notes>
Copy file name to clipboardExpand all lines: README.md
+56-18Lines changed: 56 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,18 +4,65 @@
4
4
5
5
A library that extends the Actor Framework to allow for async method execution.
6
6
7
-
The "**Async Methods Actor**" is an actor-based library that implements an infrastructure for launching async methods. By making actors inherit from the "Async Methods Actor", it is possible to launch any method without waiting for its conclusion, by sending messages child of the abstract message "**Async Message.lvclass**". This framework is especially useful for tasks that take a long time to execute which implemented as Actor methods would lock the actor until completion. The official way to implement those tasks in the Actor Framework is to code them as helper loops within the "Actor Core.vi". This however brings along the overhead of setting up a communication mechanism between Actor methods and the helper loop, thus voiding the advantage of OOP encapsulation. By means of this framework, you continue to benefit from OOP encapsulation of the Actor Framework also for long execution tasks without having to implement ad-hoc data transfer methods between methods and helper loops.
7
+
The **Async Methods Actor** is an actor-based library that implements an infrastructure for launching async methods. By making actors inherit from the **Async Methods Actor**, it is possible to launch any method without waiting for its conclusion, by sending messages child of the abstract message "**Async Message.lvclass**". This framework is especially useful for tasks that take a long time to execute which implemented as Actor methods would lock the actor until completion. The official way to implement those tasks in the Actor Framework is to code them as helper loops within the "Actor Core.vi". This however brings along the overhead of setting up a communication mechanism between Actor methods and the helper loop, thus voiding the advantage of OOP encapsulation. By means of this framework, you continue to benefit from OOP encapsulation of the Actor Framework also for long execution tasks without needing to implement boilerplate code.
8
8
9
-
## Steps required to use this library with the LSI Actor Framework Message Maker (Recommended)
9
+
## Steps required to use this library
10
10
11
-
1. Install the VIPM Package by means of the VI Package Manager. The VIPM package can be found <ahref="https://www.vipm.io/package/ls_instruments_ag_lib_async_methods_actor/"target="_blank">here</a>
11
+
1. Install the **Async Methods Actor**VIPM Package by means of the VI Package Manager. The VIPM package can be found <ahref="https://www.vipm.io/package/ls_instruments_ag_lib_async_methods_actor/"target="_blank">here</a>
12
12
2. Install the **LSI Actor Framework Message Maker** by means of the VI Package Manager. You can find details about the package <ahref="https://www.vipm.io/package/ls_instruments_ag_lib_lsi_actor_framework_message_maker/"target="_blank">here</a>
13
-
2. Create an actor, make it inherit from the "**Async Methods Actor.lvclass**" class and add some methods. You can now use your actor as you would normally do with normal LabVIEW actors
14
-
2. Choose a method of the actor that you want to execute asynchronously
15
-
3. Open **LSI Actor Framework Message Maker** from the "Tools" menu and create a message for the method you have chosen
16
-
5. Send this message through the **send VI** of your message as you would normally do within the AF
17
13
18
-
If you want to get more control over the asynchronous call you can wire a suitably configured copy of the "**Async Message Settings**" cluster to the message Send VI as shown in the following picture.
14
+
### Create Async Methods Actors
15
+
Right-click on a target within a LabVIEW project, in most cases it will be "My Computer" and click on the "Async Methods Actor" sub-menu:
Therein you will be able to choose the **Async Methods Actor** name, from which **Async Methods Actor** to inherit from, and where to store the **Async Methods Actor** on disk. Then click "OK". A new library will be created containing the **Async Methods Actor** within your project under the chosen target:
If you want to add an **Async Methods Actor** to the newly created library and inherit from the just created actor, right click on the library and launch again the **Async Methods Actor** creator:
The **Async Methods Actor** creator window will appear. Here choose a new name and choose to inherit from the previously created Async Actor. Click "OK":
In order to use the **Async Methods Actor** in your code you have to implement methods and the corresponding messages. As an example add two methods to the **Async Methods Actors** just created:
The Message Maker window will appear, select the two methods for which you want to create an **Async Message** (select the "Async Message" child of the Async Methods Actor's method to create an Async messages instead of a standard Actor messages) an then click the "Build/Update Selected Message(s)" button:
If you change either the VI Icon, the VI Description, or the VI connector pane of the **Async Methods Actor** methods you can relaunch the **LSI Actor Framework Message Maker** and rebuild the messages to reflect the changes:
### Send the Async Messages to the Async Methods Actor
62
+
63
+
Send each Async message through the corresponding **Send** method as you would normally do within the AF.
64
+
65
+
If you want to get more control over the asynchronous call you can wire a suitably configured copy of the "**Async Message Settings**" cluster to the message's **Send** methods as shown in the following picture:
19
66
20
67
21
68
@@ -27,15 +74,6 @@ Through the "**Async Message Settings**" cluster you can set:
27
74
4. a "**Report Errors (T)**" Boolean. If TRUE the standard error output of the Async Method will be reported to the calling actor.
28
75
5. a previously created concrete subclass of the "**Completion Notification Msg**" and a **Caller Enqueuer**. If both fields are set, upon completion of the "Call and Collect" Async Message method the Async Method Actor will send the aforementioned concrete "**Completion Notification Msg**" message to the caller which will enable the caller to obtain a copy of the **Async Message** and the current number of running "Call and Collect" messages of this kind. The copy of the message will allow the caller to access the GUID and FQN of the conclude Async Message by means of the corresponding Async Message properties
29
76
30
-
## Steps required to use this library with the LSI Actor Framework Message Maker (Not Recommended)
31
-
1. Subclass the "**Async Methods Actor.lvclass**" class. You can now use your actor as you would normally do with normal LabVIEW actors
32
-
2. Choose a method of the actor that you want to execute asynchronously
33
-
3. Create a message corresponding to such method as you would normally within the AF
34
-
4. Let this message inherit from "**Async Message.lvclass**"
35
-
5. Send this message through the send VI of your message as you would normally do within the AF
36
-
37
-
If you want to get more control over the asynchronous call you can use the "**Send Async Message.vi**" method of the "**Async Message.lvclass**" class. To this method you wire the message object you have created (possibly configured to match the input of your actor method by means of suitable property nodes) and optionally an "**Async Call Method**" enum that can take values "Call and Collect" or "Call and forget" and an "**VI Refnum Lifetime**" enum that can take values "Destroy on Exit", "Destroy on Actor Exit", or "Leak". The message can be also configured by setting a previously created concrete subclass of the "**Completion Notification Msg**" and a **caller enqueuer** by means of the **Async Message** properties "**Completion Notification Msg**" and "Caller Enqueuer". If both properties are set, upon completion of the "Call and Collect" Async Message method the Async Method Actor will send the aforementioned concrete "Completion Notification Msg" message to the caller which will enable the caller to obtain a copy of the **Async Message** and the current number of running "Call and Collect" messages of this kind. The copy of the message will allow the caller to access the GUID and FQN of the conclude Async Message by means of the corresponding Async Message properties
38
-
39
77
## Example Code
40
78
The library comes with an example that illustrates the full API. Within the source tree the examples can be found at the path `./Async Methods Actor Example`. When installing the VIPM package you will find the example at the path `(LabVIEW Root Path)/examples/LS Instruments AG/Async Methods Actor/Async Methods Actor Example`
41
79
@@ -65,7 +103,7 @@ Wire a properly configured (see message documentation for discovering configurat
65
103
66
104
an "**Async Call Method**" enumeration. This can take values "Call and Collect" and "Call and Forget". In the former case the "Async Methods Actor" will track the execution of the methods by waiting for their completion, in the latter case instead the actor will not wait for their completion but will just count their launch.
67
105
68
-
a "**VI Refnum Lifetime**" enumeration. This can take values "Destroy on Exit", " Destroy on Actor Exit", and “Destroy on Application Exit”. This enumeration dictates the lifetime strategy adopted for the VI Refnum of the Async Method. In the first case the "Async Methods Actor" destroys the reference as soon as the Async Method Exits, in the second case the VI Refnums will be destroyed once the “Async Method Actor” exits, while in the last case, VI Refnums are never destroyed. “Destroy on Exit” is the default option when unwired. The motivation for this setting is related to the required lifetimes of the Refnums (e.g. notifier’s references) created within the Async Method. This lifetime is the same as the VI Refnum lifetime, hence if we want they outlive the execution of the Async Method we have to set it to either “Destroy on Actor Exit” or “Destroy on Application Exit”. This option applies only to Async Methods called with the “Call and Collect” option.
106
+
a "**VI Refnum Lifetime**" enumeration. This can take values "Destroy on Exit", " Destroy on Actor Exit", and “Destroy on Application Exit”. This enumeration dictates the lifetime strategy adopted for the VI Refnum of the Async Method. In the first case the **Async Methods Actor** destroys the reference as soon as the Async Method exits. In the second case the VI Refnums will be destroyed once the “Async Method Actor” exits, while in the last case, VI Refnums are never destroyed. “Destroy on Exit” is the default option when unwired. The motivation for this setting is related to the required lifetimes of the Refnums (e.g. notifier’s references) created within the Async Method. This lifetime is the same as the VI Refnum lifetime, hence if we want they outlive the execution of the Async Method we have to set it to either “Destroy on Actor Exit” or “Destroy on Application Exit”. This option applies only to Async Methods called with the “Call and Collect” option.
69
107
70
108
a "**Report Errors (T)**" Boolean. If True the standard error output of the Async Method will be reported to the calling actor.
0 commit comments