Overview

7.3 Overview

Summary of Tcl Commands

A peer must already exist before it can participate in peer multitasking: (i.e. it has already been set up using ec_init (embedded) or ec_remote_init (remote)).

Peer multitasking occur in a multitasking phase, which is a special way for an ECLⁱPS^e side to hand over control to the external side. Effectively, instead of handing over control to a single peer, control is handed over repeatedly to all the peers that are participating in peer multitasking. The control is shared between these peers in a round-robin fashion, giving rise to a form of co-operative multitasking. The multitasking is co-operative in that each peer has to give up control, so that the control can be passed to the next multitasking peer. A peer multitasking phase is started by calling the predicate peer_do_multitask/1 in ECLⁱPS^e.

To participate in peer multitasking, a peer must be “registered” (initialised) for peer multitasking. This is done by executing the procedure ec_multi:peer_register from Tcl. Once registered, the peer will take part in subsequent multitasking phases.

The registration can set up three user-defined handlers: the start handler, the interact handler, and the end handler. During a multitasking phase, control is handed over to a multitasking peer, which invokes one of these handlers, and when the handler returns, control is handed to the next multitasking peer. The interact handler is normally invoked, except at the start (first) and end (last) of a multitasking phase. In these cases, the start and end handlers are invoked respectively.

A ‘type’ (specified in the call to peer_do_multitask/1) is associated with every multitasking phase to allow multitasking phases for different purposes (distinguished by different ‘type’s). This type is passed to the handlers as an argument. At the start of a multitasking phase, a peer should indicate if it is interested in this particular multitasking phase or not. If no peer is interested in the multitasking phase, then the multitasking phase enters the end phase after the initial round of passing control to all the multitasking peers, i.e. control is passed one more time to the multitasking peers, this time invoking the end handler. If at least one peer indicates that it is interested in the multitasking phase, then after the initial start phase, the control will be repeatedly handed over to each multitasking peer by invoking the interact handler. This phase is ended when one (or more) peer indicates that the multitasking phase should end (at which point the end phase will be entered in which the end handler will be invoked for each multitasking peer).

7.3.1 Summary of Tcl Commands

Here is a more detailed description of the Tcl procedures:

ec_multi:peer_register ?Multitask handlers

Registers for peer multitasking, and setup the (optional) multitask handlers. There handlers can be specified: a) start, invoked at the start of a multitasking phase; b) end, invoked at the end of a multitasking phase, and c) interact, invoked at other times when the peer is given control during a multitasking phase. Multitask handlers is a list specifying the handlers, where each handler is specified as two list elements of the form: type name, where type is either start, end or interact, and name is the name of the user defined handler. For example:

      ec_multi:peer_register [list interact tkecl:multi_interact_handler 
            start tkecl:multi_start_handler end tkecl:multi_end_handler]

When control is handed over to the peer during a peer multitasking phase, the appropriate handler (if defined) is invoked. When the handler returns, control is handed back to ECLⁱPS^e (and passed to the next multitasking peer). Note that events are not processed while the peer does not have control. The Tcl command update is therefore called each time the peer is given control, to allow any accumulated events to be processed. As long as the peer is given control frequently enough, then any interactions with the peer would appear to be continuous.

The handlers are invoked with the ‘type’ of the multitasking phase supplied as the first argument. This will for example allow the start handler to determine if it is interested in this multitasking phase. They can also set one of the following return codes:

continue: indicates that the peer wants to continue the multitasking phase. In particular, this should be returned by the start handler if it is interested in the multitasking phase. Note that the multitasking phase is not guaranteed to continue, as it can be terminated by another multitasking peer.
terminate: indicates the termination of a multitasking phase. The multitasking phase will enter the end phase, where the end handlers will be invoked once per peer before the multitasking phase finishes.

For example, here is the start handler used in the Tk development tools:

proc tkecl:multi_start_handler {type} {

    switch $type {
        tracer {
            # multitasking phase is `tracer'
            # only do handling of port if the tracer window exists
            if [winfo exists .ec_tools.ec_tracer] {
                tkecl:handle_tracer_port_start
                set of_interest  continue
            }
        }
        default {
            set of_interest no
            # do nothing
        }
    }

    return $of_interest
}

An error is raised if this procedure is called while the peer is already registered for multitasking.

ec_multi:peer_deregister

Deregisters peer from multitasking. After calling this procedure, the peer will not participate in any further multitasking. If this procedure is called during a multitasking phase, the peer will not participate further in that multitasking phase once control is returned. The multitasking phase will continue, unless there are no multitasking peers left, in which case an error will be raised on the ECLⁱPS^e side. The peer multitask control queue will be automatically closed.

An error is raised if this procedure is called while the peer is not registered for multitasking.

ec_multi:get_multi_status

Returns the current peer multitasking status for the peer. The values can be:

not_registered: the peer is not registered for peer multitasking.
off: the peer is registered for peer multitasking, but is not currently in a multitasking phase.
on: the peer is registered for peer multitasking, and is currently in a multitasking phase.

Note that the peer multitasking code is implemented using peer queue handlers. Thus, the peer multitask status is set to ‘on’ before the multitask start handler is called, but after the ‘ECLⁱPS^e end’ handler. Conversely, the peer multitask status is set to ‘off’ after the multitask end handler, but before the ECLⁱPS^e start handler.