5.6  Attaching Handlers to Queues

• Tcl handlers
• ECLⁱPS^e handlers

In order to handle ECLⁱPS^e I/O on queues more conveniently, it is possible to associate a handler with every queue, either on the Tcl or ECLⁱPS^e side. These handlers can be invoked automatically whenever the other side initiates an I/O operation.

5.6.1  Tcl handlers

To-ECLⁱPS^e queues

For this purpose, the to-ECLⁱPS^e queue must be created with the command argument set. The following example creates a queue that can be written from the ECLⁱPS^e side, and whose contents, if flushed, is automatically displayed in a text widget:

Tcl:      pack [text .tout]
          ec_queue_create my_out_queue toec {ec_stream_to_window "" .tout} {}

Assume that ECLⁱPS^e is then resumed, writes to the queue and flushes it. This will briefly pass control back to Tcl, the ec_stream_to_window-handler will be executed (with the stream number added to its arguments), afterwards control is passed back to ECLⁱPS^e. Note that ec_stream_to_window is a predefined handler which reads the whole queue contents and displays it in the given text widget.

From-ECLⁱPS^e queues

Similarly, a from-ECLⁱPS^e queue could be created as follows:

Tcl:      ec_queue_connect my_in_queue fromec \
                        {ec_stream_input_popup "Type here:"} {}

Assume that ECLⁱPS^e is then resumed and reads from my_in_queue. This will briefly yield control back to Tcl, the ec_stream_input_popup-handler will be executed, afterwards control is passed back to ECLⁱPS^e.

Three predefined handlers are provided:

ec_stream_to_window tag text_widget stream_nr

Inserts all the current contents of the specified queue stream at the end of the existing text_widget, using tag.

ec_stream_to_window_sync tag text_widget stream_nr ?length?

This is provided for compatibility with the Tcl remote interface. This command is essentially an alias for ec_stream_to_window, with an optional dummy argument length that is ignored.

ec_stream_output_popup label_text stream_nr

Pops up a window displaying the label_text, a text field displaying the contents of the specified queue stream, and an ok-button for closing.

ec_stream_input_popup label_text stream_nr

Pops up a window displaying the label_text, an input field and an ok-button. The text typed into the input field will be written into the specified queue stream.

When ECLⁱPS^e is initialised with the default options, its output and error streams are queues and have the ec_stream_output_popup handler associated. Similarly, the input stream is a queue with the ec_stream_input_popup handler attached. These handler settings may be changed by the user’s Tcl code.

5.6.2  ECLⁱPS^e handlers

A to-ECLⁱPS^e queue can be configured to raise an ECLⁱPS^e-event (see event/1 and the User Manual chapter on event handling) whenever the Tcl program writes something into the previously empty queue. To allow that, the queue must have been created with the event argument of ec_queue_create set, e.g.³

Tcl:  set my_out_channel [ec_queue_create my_queue toec {} my_queue_event]

Assuming something was written into the queue from within Tcl code, the ECLⁱPS^e event will be handled if the queue is flushed on the Tcl side with the command ec_flush:

Tcl:  puts $my_out_channel hello
      ec_flush [ec_streamname_to_streamnum myqueue]

If myqueue was empty, then the puts would raise the event my_queue_event. The ec_flush transfer control over to ECLⁱPS^e, so that the event can be handled.

3

It is possible to use the same name for both the queue stream itself and the event. This simplifies the event handler code because it receives that name as an argument.