Attaching Handlers to Queues

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

Tcl handlers

To-ECLiPSe queues

For this purpose, the to-ECLiPSe queue must be created with the command argument set. The following example creates a queue that can be written from the ECLiPSe 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 ECLiPSe 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 ECLiPSe. 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-ECLiPSe queues

Similarly, a from-ECLiPSe queue could be created as follows:

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

Assume that ECLiPSe 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 ECLiPSe.

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 ECLiPSe 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.

ECLiPSe handlers

A to-ECLiPSe queue can be configured to raise an ECLiPSe-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.^5.3

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 ECLiPSe 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 ECLiPSe, so that the event can be handled.