Data collector monitoring functions | CPN Tools help |
CPN ML |
Monitoring functions, Data collector monitors
Each one of the Data collector monitors has the following monitoring functions:
NONE
then nothing will happen. If the function returns a value of the form SOME x
where x
is a number, then x
will be used to update statistics and it will be saved in a log file (if the Logging
option for the data collector monitor is checked).
The predicate function is called after simulation steps. When the predicate function returns true, the observation and action functions are called.
The observation function examines the monitored nodes, and returns a numerical value.
The action function uses the numerical values that are returned by the observation function to update statistics, and the values are also saved in a log file (if the Logging
option for the data collector monitor is checked).
The stop function is analogous to the initialization function, but it is called when simulation stop criteria are met.
Accessibility of the monitoring functions for the different kinds of data collector monitors:
initialization | predicate | observation | action | stop | |
Marking size monitor | hidden | hidden | hidden | hidden | hidden |
List length monitor | hidden | hidden | hidden | hidden | hidden |
Count transition occurrences monitor | hidden | hidden | hidden | hidden | hidden |
Generic data collector | accessible | accessible | accessible | hidden | accessible |
Function types for the accessible functions
init: markings -> <numerical type> option |
initialization function |
pred: subnet -> bool |
predicate function |
obs: subnet -> <numerical type> |
observation function |
stop: markings -> <numerical type> option |
stop function |
For more information about the subnet
and markings
data types see Data types for monitored subnets.
For each generic data collector monitor the type <numerical type>
can be one of the following:
real
int
IntInf.int
<numerical type> option
. This means that they can return the following values:
NONE
SOME x
x
has type <numerical type>
. For more information about optional values please see the Option structure in the SML Basis Library Manual.
The <numerical type>
must be the same for the observation, initialization, and stop functions in a given monitor. For example, if the observation function returns values of type int
, then the stop function must return values of type int option
, i.e. the stop function cannot return values of type real option
.
Note that when an observation, initialization, or stop function returns integer values, the values are converted to infinite integers, i.e. IntInf.int, in order to avoid Overflow
exceptions when calculating statistics.
In the examples below, two different subnets of the Simple Protocol net will be considered. One subnet consists just of the place B
, which is on the page Top
.
The other subnet consists of place B
and its surrounding transitions on page Top
.
Additional examples of data collector monitoring functions can be found in the example net for the Queue System.
The arguments for an initialization function will be the same for the two subnets described above. This is due to the fact that transitions cannot be inspected in initialization functions, and that both subnets contain the same place.
This initialization function returns the value NONE
, which means that no data value will extracted from the net by the monitor before the first step of a simulation.
fun init (Top'B_1_mark : INTxDATA ms) = NONE
This initialization function returns a value an integer option, as indicated by SOME ...
which means that a data value will be extracted from the net by the monitor before the first step of a simulation. In this case the data value is equal to the number of tokens on the place B
in the initial marking. The size
function is a function for multi-sets.
fun init (Top'B_1_mark : INTxDATA ms) = SOME (size Top'B_1_mark)
This predicate function is for a monitor that is associated with just place B
from the Simple Protocol net. The predicate function will be invoked after every step in a simulation, because the monitor is not associated with any transitions. The function will return true each time it is invoked, i.e. it will return true after every simulation step.
fun pred (Top'B_1_mark : INTxDATA ms) = true
This predicate function is for a monitor that is associated with place B
and its surrounding transitions from the Simple Protocol net.
The predicate function returns true when either of the two transitions occurs, and it does not examine the marking of the place B
. This function returns true each time one of the transitions surrounding place B
occurs, i.e. when the marking of place B
changes.
fun pred (bindelem, Top'B_1_mark : INTxDATA ms) = let fun predBindElem (Top'Receive_Packet (1, {k,n,p,str})) = true | predBindElem (Top'Transmit_Packet (1, {n,p,r,s})) = true | predBindElem _ = false in predBindElem bindelem end
This observation function is for a monitor that is associated with just place B
. The function will return the number of tokens on place B
each time it is invoked.
fun obs (Top'B_1_mark : INTxDATA ms) = size Top'B_1_mark
This observation function is for a monitor that is associated with place B
and its surrounding transitions. The function will also return the number of tokens on place B
each time it is invoked. The function ignores the binding element argument bindelem
.
fun obs (bindelem, Top'B_1_mark : INTxDATA ms) = let fun obsBindElem (Top'Receive_Packet (1, {k,n,p,str})) = 0 | obsBindElem (Top'Transmit_Packet (1, {n,p,r,s})) = 0 | obsBindElem _ = ~1 in size Top'B_1_mark end
This observation function is for a monitor that is associated with place B
and its surrounding transitions. The observation function will be invoked when the predicate function for the monitor returns true, and it may only be invoked after the Receive_Packet
or the Transmit_Packet
transitions occur.
fun obs (bindelem, Top'B_1_mark : INTxDATA ms) = let fun obsBindElem (Top'Receive_Packet (1, {k,n,p,str})) = size (filter (fn (sn,data) => sn=n) Top'B_1_mark) | obsBindElem (Top'Transmit_Packet (1, {n,p,r,s})) = size (filter (fn (sn,data) => sn=n) Top'B_1_mark) | obsBindElem _ = ~1 in obsBindElem bindelem end
If the observation function is invoked after the Receive_Packet
occurs, then the observation function will return the number of tokens on place B
that have a sequence number equal to the value bound to the variable n
when the transition occurred. The size
and filter
functions are functions for multi-sets. The filter
function takes two arguments: a predicate function and a multi-set. The function will return all of the elements in the multi-set which satisfy the predicate.
Consider the statement (filter (fn (sn,data) => sn=n) Top'B_1_mark)
. The value Top'B_1_mark
will correspond to the tokens on place B
, i.e. it will be a multi-set of values of type INTxDATA
.
The function size (fn (sn,data) => sn=n)
is a predicate function that takes an argument of type INTxDATA
, and it compares the first value in the pair to the value n
, where n
is the value that was bound to the variable n
when either the transition Receive_Packet
or Transmit_Packet
occurred.
When the filter
function is invoked, the predicate function will be applied to each element in the multi-set Top'B_1_mark
, i.e. to each token on place B
. When the function filter
applies the predicate function to the marking of place B
, it will return the tokens on place B
that have sequence number equal to n
. The size
function is then used to find out how many tokens on place B
have sequence number equal to n
.
The arguments for stop functions for the two subnets will be the same because stop functions cannot examine transitions and because the two subnets contain the same place. Stop functions are similar to initialization functions, but they are invoked when simulation stop criteria are met (rather than before the first step in a simulation).
This stop function returns the value NONE
, which means that no data value will extracted from the net by the monitor when simulation stop criteria are met.
fun stop (Top'B_1_mark : INTxDATA ms) = NONE
This stop function returns a value an integer option, as indicated by SOME ...
which means that a data value will be extracted from the net by the monitor when simulation stop criteria are met. In this case the data value is equal to the number of tokens on the place B
in the final marking. The size
function is a function for multi-sets.
fun stop (Top'B_1_mark : INTxDATA ms) = SOME (size Top'B_1_mark)