Description
Circuit methods (MTHDs) are the principal repositories for application processing code. Unlike threads, where control persists, circuit methods are scheduled. They execute and return (like GUI call-backs), and in so doing, automatically close their consumed event tree; releasing their interest in consumed resources, in the same manner that conventional functions execute returns and release automatic stack data. Closing the output leaves of the event tree, automatically propagates control to the next processing stage(s), and ensures that sequential functionality is repeatably reproduced; but in this case, in a concurrent processing domain.
Methods should always be used in preference to 'threads' because they provide almost identical functionality (preemptive asynchronous execution) but consume a small fraction of the resources required by conventional threads. They can also be load-balanced across entire networks, whilst threads are only scheduled within a single process.
Methods take three 'graphical' forms (see above). The first (leftmost) makes a single connection. The second (middle) makes two connection and will execute when both inputs have been (implicitly) collected. The third form is similar to the the second, but in tis case collection is ordered (as d illustrated above, the leftmost face will collect first).
Definition Content
The following information is required in order to define a circuit method (MTHD).
Stack Size
This attribute specifies the method's stack requirement in bytes. Note that this will not necessarily cause the runtime to allocate space, but will allow it to ensure that all worker threads that have the method's executing priority, have sufficient stack to accommodate the largest method stack requirement.
Instance Content
The following information is required in order to instantiate a circuit method.
Name
Instance name (see Object Names)
Dimension
Instance dimensionality (see Object Dimensionality)
Presence
Instance presence flag (see Object Presence)
Execution Priority
Circuit methods execute preemptively in accordance with their priority (even at network scope - see mobility). CDL supports 31 execution priorities. One is the lowest execution priority and 31 is the highest.
Mobility
This attribute determines whether the instantiated method will be executed by the master process or farmed out to slave processes.
Data Affinity
This attribute determines whether a slave-able method's state data is automatically flushed back to the master (Endpoint), or left in the slave process that last executed it (Floatpoint). In the latter case, the state can be moved directly from slave to slave (without going via the master) each time the executing process changes. Floatpoint affinity can therefore reduce total bandwidth but in the event that the owning slave makes an unscheduled exit, may result in loss of definitive data.
Reentrancy
This attribute determines the reentrancy of each method element. Methods with reentrancy greater than one can be simultaneously executed by more than one worker thread. For this reason, methods that have non-empty state/workspace objects seldom have reentrancy greater than one. If multiple reentrancy is required for stateful methods then locks can be used to arbitrate state and/or workspace access (see circuit locks). Stateful methods with reentrancy greater than one cannot be designated as slave-able.
Occasionally Over-Rideable Functions
The following functions have generated bodies that can be 'over-ridden' (see Browsing and Inserting User Code);
Create Function
This automatically generated over-rideable function creates the MTHD and is called automatically once only when its parent circuit instance is created.
Integrate Function
This automatically generated over-rideable function populates the MTHD's parent pointer and is called automatically once only when its parent circuit instance is integrated.
Connect Function
This automatically generated over-rideable function connects the MTHD's trigger and manual connection(s) and is called automatically once only when its parent circuit instance is connected.
Activate Function
This automatically generated over-rideable function activates the MTHD, and is called automatically once only when the parent circuit instance is activated.
Execute Function
This automatically generated over-rideable function is automatically called each time the MTHD's trigger connection delivers an event. The generated code will call the Process function.
Frequently Over-Rideable Functions
The following functions have generated bodies that usually require insertion of user code (see Browsing and Inserting User Code);
Initialize Function
This user defined function is entered using the Blueprint editor and is automatically called once only before the MTHD is first executed.
Process Function
This user defined function is entered using the Blueprint editor and is automatically called each time the MTHD's trigger connection delivers an event. If the trigger event is overloaded (contains irregular multiplexed events) then the translator will generate one entry point for each overload (see Multiplexors).
Exit Function
This user defined function is entered using the Blueprint editor and is automatically called once only on process exit.
Member Functions
Circuit methods support the following member functions;
Name()
Returns the address of a string containing the executing element's creation name.
NumDimensions()
Returns the number of dimensions that the executing instance was created with. This does not include the dimensionality of the parent circuit which can be obtained through use of the 'parent' member function (see below).
Dimensions()
Returns the address of an unsigned integer array containing the executing MTHD's creation dimensions. The first element of the array contains the fastest varying (rightmost) dimension.
Element()
Returns the address of an unsigned integer array containing the executing MTHD element's particular coordinates.
Parent()
Returns a reference to the executing MTHD's parent circuit. If the MTHD is defined in-line then the function will return a pointer of the parent circuit's derived instance type. If the MTHD is defined explicitly then it will return a reference of the base circuit type and will therefore only provide this function and the four member functions described above (in this section).
Workspace()
Returns a reference to the executing MTHD element's workspace object (see State and Workspace Objects).
State()
Returns a reference to the executing MTHD element's state object (see State and Workspace Objects).
Executable()
Returns TRUE if the executing method could be scheduled to the executing process. If TRUE, then the method's workspace object will need to be initialized.
Definitive()
Returns TRUE if the executing method's state object has a definitive instance in the executing process. If TRUE, then the MTHD's state object will need to be initialized.
Pin()
This function will 'pin' the executing method element to the specified slave. Once 'pinned', the method will always be scheduled to the specified slave. This function can be safely executed in autonomous builds but does not have any effect. This ensures repeatable execution in all configurations. Pinning is usually adopted for methods that have large state objects that cannot be efficiently moved between subsequent executions. Pinning is typically performed in the method element's 'Initialise' code and should always be performed before State and/or Workspace objects are constructed and initialized (see State and Workspace Objects).
SetLoopRange()
$TBD.
Notes
If a process contains methods whose manual connections can block (e.g. a write to a transient store), then the scheduler may need to create additional threads if it detects potential deadlocks. This is transparent to the application, but for optimal use of resources, methods should always collect as many of their inputs and outputs as possible in their trigger connection(s). If for example, a method uses its input data to decide which of two output stores require updating, then it is usually best to open both stores for write in the method's trigger connection, and then abort the unused write.
Example
See Heavy vs. Light-Weight Execution.