1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): Kish Shen, IC-Parc 20% 21% END LICENSE BLOCK 22% 23% $Id: embtclmulti.tex,v 1.1 2006/09/23 01:49:04 snovello Exp $ 24% 25% Author: Kish Shen, IC-Parc 26% 27%---------------------------------------------------------------------- 28\chapter{Tcl Peer Multitasking Interface} 29\label{chaptclmulti} 30%HEVEA\cutdef[1]{section} 31%---------------------------------------------------------------------- 32 33\section{Introduction} 34 35This chapter describes how to use the peer multitasking interface with 36the Tcl peer interfaces. The usage is the same regardless of if the Tcl 37interface is of the embedded or remote variants. 38 39The facilities described here allows a Tcl peer to participate in peer 40multitasking, so that different peers can apparently interact with 41{\eclipse} simultaneously. This would for example allow GUI windows that 42are implemented using different peers for the same {\eclipse} process to be 43appear as if they can interact with the host {eclipse} side at the same 44time. 45 46%---------------------------------------------------------------------- 47\section{Loading the interface} 48%---------------------------------------------------------------------- 49The peer multitasking interface is provided as a Tcl-package called {\bf 50eclipse_peer_multitask}, and must be loaded along with either the embedded 51({\bf eclipse}) or remote ({\bf remote_eclipse}) variant of the Tcl peer 52interface. 53\begin{quote}\begin{verbatim} 54lappend auto_path "/location/of/my/eclipse/lib_tcl" 55package require remote_eclipse 56package require eclipse_peer_multitask 57\end{verbatim}\end{quote} 58\index{eclipse_peer_multitask (Tcl package)} 59 60%---------------------------------------------------------------------- 61\section{Overview} 62%---------------------------------------------------------------------- 63A peer must already exist before it can participate in peer multitasking: 64(i.e. it has already been set up using ec_init (embedded) or ec_remote_init (remote)). 65 66Peer multitasking occur in a {\it multitasking phase}, which is a special 67way for an {\eclipse} side to hand over control to the external 68side. Effectively, instead of handing over control to a single peer, 69control is handed over repeatedly to all the peers that are participating 70in peer multitasking. The control is shared between these peers in a 71round-robin fashion, giving rise to a form of co-operative 72multitasking. The multitasking is co-operative in that each peer has to 73give up control, so that the control can be passed to the next multitasking 74peer. A peer multitasking phase is started by calling the predicate 75\bip{peer_do_multitask/1} in {\eclipse}. 76 77 78To participate in peer multitasking, a peer must be ``registered'' 79(initialised) for peer multitasking. This is done by executing the 80procedure {\bf ec_multi:peer_register}\index{ec_multi:peer_register (Tcl command)} 81from Tcl. Once registered, the peer will take part in subsequent 82multitasking phases. 83 84 85The registration can set up three user-defined handlers: the {\bf 86start} handler, the {\bf interact} handler, and the {\bf end} handler. 87During a multitasking phase, control is handed over to a multitasking peer, 88which invokes 89one of these handlers, and when the handler returns, control is handed 90to the next multitasking peer. The interact handler is normally invoked, 91except at the start (first) and end (last) of a multitasking phase. In 92these cases, the start and end handlers are invoked respectively. 93 94A `type' (specified in the call to \bip{peer_do_multitask/1}) is associated 95with every multitasking phase to allow multitasking phases for different 96purposes (distinguished by different `type's). This type is passed to the 97handlers as an argument. At the start of a multitasking phase, a peer 98should indicate if it is interested in this particular multitasking phase 99or not. If no peer is interested in the multitasking 100phase, then the multitasking phase enters the end phase after the initial 101round of passing control to all the multitasking peers, i.e. control is 102passed one more time to the multitasking peers, this time invoking the end 103handler. If at least one peer indicates that it is interested in the 104multitasking phase, then after the initial start phase, the control will be 105repeatedly handed over to each multitasking peer by invoking the interact 106handler. This phase is ended when one (or more) peer indicates that the 107multitasking phase should end (at which point the end phase will be entered 108in which the end handler will be invoked for each multitasking peer). 109 110\subsection{Summary of Tcl Commands} 111Here is a more detailed description of the Tcl procedures: 112\begin{description} 113\item[\index{ec_multi:peer_register (Tcl peer multitasking)}{\bf 114 ec_multi:peer_register {\it ?Multitask handlers}}] \ \\ 115 Registers for peer multitasking, and setup the (optional) multitask handlers. 116 There handlers can be specified: a) start, invoked at the start of a 117 multitasking phase; b) end, invoked at the end of a multitasking 118 phase, and c) interact, invoked at other times when the peer is 119 given control during a multitasking phase. {\bf Multitask handlers} 120 is a list specifying the handlers, where each handler is specified 121 as two list elements of the form: {\tt type name}, 122 where type is either {\bf start}, {\bf end} or {\bf interact}, and 123 name is the name of the user defined handler. For example: 124\begin{verbatim} 125 ec_multi:peer_register [list interact tkecl:multi_interact_handler 126 start tkecl:multi_start_handler end tkecl:multi_end_handler] 127\end{verbatim} 128 When control is handed over to the peer during a peer multitasking 129 phase, the appropriate handler (if defined) is invoked. When the 130 handler returns, control is handed back to {\eclipse} (and passed 131 to the next multitasking peer). Note 132 that events are not processed while the peer does not have control. 133 The Tcl command {\bf update} is therefore called each time the peer 134 is given control, to allow any accumulated events to be processed. 135 As long as the peer 136 is given control frequently enough, then any interactions with the 137 peer would appear to be continuous. 138 139 The handlers are invoked with the `type' of the multitasking phase 140 supplied as the first argument. This will for example allow the 141 start handler to determine if it is interested in this multitasking 142 phase. They can also set one of the following return codes: 143\begin{description} 144\item[continue] indicates that the peer wants to continue the multitasking 145 phase. In particular, this should be returned by the start handler if it is 146 interested in the multitasking phase. Note that the multitasking phase is 147 not guaranteed to continue, as it can be terminated by another 148 multitasking peer. 149\item[terminate] indicates the termination of a multitasking phase. The 150 multitasking phase will enter the end phase, where the end handlers 151 will be invoked once per peer before the multitasking phase finishes. 152\end{description} 153 For example, here is the start handler used in the Tk development 154 tools: 155\begin{verbatim} 156proc tkecl:multi_start_handler {type} { 157 158 switch $type { 159 tracer { 160 # multitasking phase is `tracer' 161 # only do handling of port if the tracer window exists 162 if [winfo exists .ec_tools.ec_tracer] { 163 tkecl:handle_tracer_port_start 164 set of_interest continue 165 } 166 } 167 default { 168 set of_interest no 169 # do nothing 170 } 171 } 172 173 return $of_interest 174} 175 176\end{verbatim} 177 178An error is raised if this procedure is called while the peer is already 179registered for multitasking. 180 181\item[\index{ec_multi:peer_deregister (Tcl peer multitasking)}{\bf 182 ec_multi:peer_deregister}] \ \\ 183 Deregisters peer from multitasking. After calling this procedure, the 184 peer will not participate in any further multitasking. If this 185 procedure is called during a multitasking phase, the peer will not 186 participate further in that multitasking phase once control is 187 returned. The multitasking phase will continue, unless there are no 188 multitasking peers left, in which case an error will be raised on the 189 {\eclipse} side. The peer multitask control queue will be 190 automatically closed. 191 192 An error is raised if this procedure is called while the peer is 193 not registered for multitasking. 194 195\item[\index{ec_multi:get_multi_status (Tcl peer multitasking)}{\bf 196 ec_multi:get_multi_status}] \ \\ 197 Returns the current peer multitasking status for the peer. The values 198 can be: 199\begin{itemize} 200\item not_registered: the peer is not registered for peer multitasking. 201\item off: the peer is registered for peer multitasking, but is not 202 currently in a multitasking phase. 203\item on: the peer is registered for peer multitasking, and is currently in 204 a multitasking phase. 205\end{itemize} 206 207Note that the peer multitasking code is implemented using peer queue 208handlers. Thus, the peer multitask status is set to `on' 209before the multitask start handler is called, but {\it after\/} the 210`{\eclipse} end' handler. 211%%% Kish, this didn't seem to make any sense: 212% invoked when control is being handed to the peer (as set up in {\bf 213% ec_running_set_commands}. 214Conversely, the peer multitask status is set to 215`off' after the multitask end handler, but {\it before\/} the {\eclipse} 216start handler. 217\end{description} 218 219\section{Example} 220 221Here we present a simple example use of the Tcl peer multitasking 222facilities. The full programs (Tcl and {\eclipse} code) are available in 223the {\eclipse} distribution as {\tt example_multi.ecl} and {\tt 224 example_multi.tcl}. 225 226 227The Tcl program uses the remote Tcl peer interface to create a window that 228interacts with the {\eclipse} process it is attached to. Multiple copies of 229the program can be run, and attached to the same {\eclipse} process with a 230different remote peer. Each window has three buttons: 231\begin{itemize} 232\item run: a button to send an ERPC goal to {\eclipse} (in this case a simple 233 writeln with the peer name; 234\item end: a button to end interaction with {\eclipse} and return control 235 to {\eclipse}; 236\item reg: a button to toggle the registration/deregistration of the peer 237 for peer multitasking; 238\end{itemize} 239 240The program interacts with {\eclipse} when the run button is pressed. This 241can be done either during a peer multitasking phase, or when the program's specific 242peer is given control on its own. When the peer is given control on its 243own, only it can interact with {\eclipse}; while during peer multitasking, 244all the multitasking peers (the copies of the program that are running) can 245interact with {\eclipse}, i.e.\ the run buttons in all the windows can all 246be pressed. 247 248After attaching to {\eclipse} with {\bf ec_remote_init}, the program sets 249various handlers for the handing of control between {\eclipse} and itself 250with {\bf ec_running_set_commands}: 251 252\begin{verbatim} 253 254ec_running_set_commands ec_start ec_end {} disable_buttons 255 256\end{verbatim} 257 258The handlers for when control is handed back to {\eclipse}, {\tt ec_start}, 259and when control is handed over from {\eclipse}, {\tt ec_end}, are defined 260thus: 261 262\begin{verbatim} 263 264proc ec_end {} { 265 if {[ec_multi:get_multi_status] != "on"} { 266 enable_buttons 267 } 268} 269 270proc ec_start {} { 271 if {[ec_multi:get_multi_status] != "on"} { 272 disable_buttons 273 } 274} 275 276\end{verbatim} 277 278{\tt enable_buttons} and {\tt disable_buttons} enables and disables the 279buttons for the window, respectively. The code tests if the peer is 280multitasking with {\tt ec_multi:get_multi_status}. This is needed because 281during a peer multitasking phase, control is repeatedly handed back and 282forth, and we don't want the buttons to be repeatedly enabled and disabled 283during this phase. 284 285Next, the program registers the peer for peer multitasking: 286 287\begin{verbatim} 288 289 ec_multi:peer_register [list start multi_start_handler \ 290 interact multi_interact_handler] 291 292\end{verbatim} 293 294No special handler is 295needed for the end of multitasking, as no special action is needed beyond 296disabling the buttons. The return code is stored in a global variable {\tt 297 return_code}. The start handler is defined thus: 298 299\begin{verbatim} 300proc multi_start_handler {type} { 301 global return_code 302 303 if {$type == "demo"} { 304 set return_code continue 305 enable_buttons 306 } else { 307 set return_code no 308 } 309 return $return_code 310} 311\end{verbatim} 312 313As discussed, multitasking phases can be of different types. For 314demonstrating this multitasking features of this example program, the type 315is ``demo''. Therefore the handler tests for this and enables the button if 316the phase is ``demo''. On the {\eclipse} side, the multitasking phase is 317started with the following predicate call: 318 319\begin{verbatim} 320 peer_do_multitask(demo), 321\end{verbatim} 322 323The interact handler is defined thus: 324 325\begin{verbatim} 326proc multi_interact_handler {type} { 327 global return_code 328 329 if {$return_code == "terminate"} { 330 disable_buttons 331 } 332 return $return_code 333\end{verbatim} 334 335The code checks for the two cases where the user has requested to terminate 336the multitasking phase by pressing the {\tt .end} button, and disables the 337buttons. The end button itself invokes the following code to set {\tt 338 return_code}: 339 340 341\begin{verbatim} 342proc end_interaction {} { 343 global return_code 344 set return_code terminate 345 if {[ec_multi:get_multi_status] != "on"} { 346 ec_resume 347 } 348} 349\end{verbatim} 350 351The code checks if it is in a peer multitasking phase, and if so, 352{\tt return_code} is set to {\tt terminate}, so that when the handler 353returns, the multitasking phase will terminate. 354Otherwise, the peer has been explicitly handed control exclusively, 355and so control is handed back to {\eclipse} in the normal way using {\bf 356 ec_resume}. 357 358The program also allows a peer to deregister from multitasking or, if 359already deregistered, to register again for multitasking. This is handling 360by the following two procedures: 361 362\begin{verbatim} 363proc register_for_multi {} { 364 ec_multi:peer_register [list start multi_start_handler] 365 .reg configure -command {deregister_for_multi} 366 .reg configure -text "Deregister multitasking" 367} 368 369proc deregister_for_multi {} { 370 ec_multi:peer_deregister 371 .reg configure -command {register_for_multi} 372 .reg configure -text "Register multitasking" 373} 374\end{verbatim} 375 376\noindent 377Pressing the {\tt .reg} button will either call {\tt register_for_multi} or 378{\tt deregister_for_multi}, depending on if the peer is currently 379deregistered or registered for peer multitasking (respectively). The 380procedure also changes the button to toggle to the other state. 381 382Pressing the button during a peer multitasking phase will remove the peer 383from multitasking immediately. If pressed while the peer is given exclusive 384control, the peer will not participate in future multitasking phase (unless 385it is re-registered). 386 387%HEVEA\cutend 388 389