|
1 | 1 | # Iterator Actor |
2 | 2 |
|
3 | 3 | ## Authors |
4 | | -Andrea Vaccaro, Albert Adiyatullin |
| 4 | +Andrea Vaccaro, Albert Adiyatullin |
| 5 | +LS Instruments AG |
5 | 6 |
|
6 | 7 | # Description |
7 | 8 |
|
8 | | -A library implementing a high-level Actor Framework-based Iterator. The caller Actor can configure the Iterator Actor to iteratively execute one of its methods by creating the corresponding Actor Framework. |
| 9 | +A library implementing a high-level Actor Framework-based Iterator. The caller Actor can configure the Iterator Actor to iteratively execute one of its methods by creating the corresponding Actor Framework messages. |
9 | 10 |
|
10 | 11 | ## Main Features |
11 | 12 |
|
12 | | -* Fully Actor Framework Based |
13 | | -* Iterate at a certain time period |
14 | | -* Waits on iteration completion |
15 | | -* Prepare and Conclude iterations definable |
16 | | -* Multiple iterator end condition definable: number of iterations, time elapsed,iteration result |
| 13 | +* Fully Actor Framework Based. |
| 14 | +* Iterate at a certain time period. |
| 15 | +* Waits on iteration completion and reports an error to caller if the corresponding timeout is exceeded. |
| 16 | +* Prepare and Conclude iterations definable. |
| 17 | +* Multiple iterator end condition definable: number of iterations, time elapsed, iteration result. |
| 18 | + |
| 19 | +## Library Walk-Through |
| 20 | + |
| 21 | +### Caller Actor Preparation |
| 22 | +Implement the methods that are going to be executed as Prepare, Iterate, Conclude iteration steps. Create the corresponding AF messages. |
| 23 | + |
| 24 | +### Configure and Launch the Iterator |
| 25 | + |
| 26 | +* Place an "Itearator NR Actor.lvclass" constant on the block diagram. |
| 27 | +* Place a "Iterator Settings.ctl" constant on the block diagram and type in the relevant desired settings. In this case, as shown in the picture, we wish to perform 100 iterations ("Active Stop Conditions.Number of Iterations" set to TRUE and "Number of Iterations" set to 100). |
| 28 | +* Bundle to the resulting cluster the messages created before to the fields "Prepare Msg", "Iterate Msg", "Conclude Msg". |
| 29 | +* Wire the "Itearator NR Actor.lvclass" constant to a property node and set the "Settings" property to the "Iterator Settings.ctl" cluster just prepared. |
| 30 | +* Launch the just configured "Itearator NR Actor.lvclass" actor by means of the "Launch Nested Actor.vi" AF method and store the Iterator enqueuer. |
| 31 | + |
| 32 | + |
| 33 | + |
| 34 | +#### Alternative "Active Stop Condition" Configurations |
| 35 | +The "Active Stop Condition" cluster can be configured to trigger different stop conditions. The different conditions can be mixed. The other stop conditions are the following: |
| 36 | +##### Time Elapsed |
| 37 | +If we set the "Time Elapsed" Boolean flag to TRUE the Iterator will stop after the iteration time reaches a value specified by the "Time Before Stop (ms)" value in milliseconds. |
| 38 | +##### Iteration Result |
| 39 | +If we set the "Iteration Result" Boolean flag to TRUE we can stop the iteration internally by sending the Break message to the Iterator. If the flag is set to FALSE sending the Break message will have no effect. |
| 40 | + |
| 41 | +If the user wants to know about which condition triggered the Iterator stop, he has to subcalss the abstract message "Iterator Report Iterations End Msg.lvclass" that is sent to the caller at the end of the iteration. The concrete implementation should be stored in the active "Iteration Settings.ctl" cluster as illustrated in the previous screenshot. Such message bears the "Stop Reason" enum which clarifies which condition triggered the Iterator stop and the possible iterator errors occurred during the iterator operation. |
| 42 | + |
| 43 | +The "Stop Reason" possible values are the following: |
| 44 | +* Number of Iterations. |
| 45 | +* Elapsed Time. |
| 46 | +* Stop Internally: One of the iteration step execution sent the Break message to the Iterator and the "Iteration Result" stop condition was active. |
| 47 | +* Stopped Externally: the caller actor has sent the "Stop Iterations" message to the iterator. This "Stop Reason" is not subject to any stop condition being enabled. |
| 48 | + |
| 49 | +### Errors Reported |
| 50 | +#### Errors Reported by the "Iterator Report Iterations End Msg.lvclass" Message |
| 51 | +* **code 7900**: Input parameters are not valid. |
| 52 | +* **code 7901**: Preparation call timed out. |
| 53 | +* **code 7902**: Iteration call timed out. |
| 54 | +* **code 7903**: Conclusion call timed out. |
| 55 | + |
| 56 | +#### Errors Reported to the Caller's "Handle Error" |
| 57 | +* **code 7904**: Cannot break Iterators configured with "Auto Iteration Notification" OFF. |
| 58 | +* **code 7905**: Cannot break, Iterator not iterating. |
| 59 | +* **code 7906**: Cannot stop iterations, Iterator not iterating. |
| 60 | +* **code 7907**: Cannot start iterations, Iterator already iterating. |
| 61 | + |
| 62 | +### Starting/Stopping Iterations |
| 63 | +To start the iterations send the "Start Iterasions Msg.lvclass" to the iterator: |
| 64 | + |
| 65 | + |
| 66 | + |
| 67 | +To stop the iterations send the "Stop Iterasions Msg.lvclass" to the iterator: |
| 68 | + |
| 69 | + |
| 70 | + |
| 71 | +### Changing Iterator's Setting During its Execution |
| 72 | +To change the Iterator settings during its execution the user has to send the "Write Settings Msg.lvclass" to the iterator: |
| 73 | + |
| 74 | + |
| 75 | + |
| 76 | +Pay attenton that this will overwrite ***all*** the settings. |
| 77 | +### Stopping the Iterator |
| 78 | +Since the iterator is generally launched by means of the "Launch Nested Actor.vi" AF method with the Auto-Stop condition set to the default TRUE, the iterator will automatically stop when the caller actor stop. If for any particular reason one wants to explicitly stop the Iterator sending the stop message will do so. |
| 79 | + |
0 commit comments