tclmsgque − tcl interface to the libmsgque library

msgque option ?arg arg ...?

The msgque project is an infrastructure to link applications together to act like a single application. To link mean distributing work from one application to an other application an wait or not wait for an answer. The linking is done using unix or inet domain sockets and is based on packages send from one application to an other application and back. The tclmsgque project is used to handle all the different aspects for setup and maintain the link and is responsible for:

- starting and stopping the different applications

- starting and stopping the communication interface

- sending and receiving packages

- reading and writing data from or into packages

- setup and maintain the event-handling for asynchronous transfers

- propagate warnings or errors

The msgque command provides several operations on a message-queue object used to link applications together and is the only command created by tclmsgque. Any unique abbreviation for option is acceptable. The valid options are:

msgque create ?option option ...?

Create a new message-queue object using options for configuration and returns the name of a new command called context. The main purpose of the msgque command is to create and manage one or more new context(s) using

set context [msgque create ...]

for creation, and

rename $context ""

for deletion. The new context is used for doing the main actions like sending or receiving of data. The valid options are:

--debug NUMBER

Debug a message-queue application. Valid values are 0 <= NUMBER <= 9 using 0 for "no debugging" and 9 for "maximum debugging". (default: 0)

--name STRING

Use STRING as name of the new message-queue object. The name shows up in the debugging output and is used as prefix for the new created command. (default: the name of the executable)

--string

Use, as much as possible, strings in the package object. Convert any native data-type like integer or double into strings (sending) and back to native (receiving). (default: use binary)

--silent

Don’t write any output to stdout or stderr. (default: write to stdout or stderr)

--checktime SEC

The server will check every SEC seconds the connection to the client. If the check fails the server will shutdown itself (default: 16 seconds)

--timeout SEC

At startup the client is waiting for maximum SEC seconds to connect to the server (default: 20 seconds)

--buffersize NUM

Set the send and receive buffersize to NUM (default: 4KB)

--inetd

This option has different usage for the client and for the server. The client does not startup the server and expect a running server already available. The server expect to be started by the inetd (xinetd) super-server and does not open an server socket. (default: not set)

--tcp

Use inet-domain-sockets for the client/server link using the following options only valid for --tcp:

--host NAME

Use the hostname NAME as the remote target of the tcp connection (default: localhost)

--port NUMBER

Use the port NUMBER as the remote target of the tcp connection. If the NUMBER is a character string the port-name have to be resolved by the local port-name resolution (default: 10243)

--myhost NAME

Use the hostname NAME as the local target of the tcp connection and is used to select a different interface (default: localhost)

--myport NUMBER

Use the port NUMBER as the local target of the tcp connection. If the NUMBER is a character string the port-name have to be resolved by the local port-name resolution (default: random)

--uds

Use unix-domain-sockets for the client/server link using the following option only valid for --uds:

--file NAME

Use the filename NAME as the local target of the uds connection (default: random)

--parent CONTEXT

Create a child message-queue of parent CONTEXT. A child is using the same server as the parent but a different context. With a different context a child is able to act on different services as the parent and is using a different namespace on the shared server (default: create a parent and not a child)

set PARENT [msgque create ...]
set CHILD [msgque create --parent $PARENT ...]

--server

Create the new message-queue in server mode

--config CMD

Use CMD to configure the server services. The request for a new context is done by the child and the server acts on this request. For every new context the server creates the internal data structures and finally calls CMD to configure the new created context. Mainly the configuration have to create the services the server is working on. (default: no server)

proc MyConfig {context} {
  $context service create SERVICE_NAME SERVICE_TCL_PROC
  ...
}
msgque create --server --config MyConfig ...

--filter, --FTRproc tclproc, --EOFproc tclproc

Options only useable in filter mode, see FILTER MODE below for details.

msgque const option

Helper command to retrieve pre-defined system constants and is used mainly for testing. The valid options are:

maxI, minI

Get the largest or smallest integer value.

maxW, minW

Get the largest or smallest wide integer value.

maxD, minD

Get the largest or smallest double value.

msgque print option tclObj

Helper command to return tclObj related information’s and is used mainly for testing. The valid options are:

object

Print out all information’s available for tclObj.

objType

Print out only the type information for tclObj.

msgque help ?options?

Command to return a help summary. The valid options are:

-options

only the msgque options help page will be returned.

A context is an useable message-queue object created by: msgque create ... and is destroyed with: rename $context "". The context is used for sending and receiving data, setup and delete services and to manage the event-queue.

$context send ?option option ...? token ?arg arg ...?

The send command is used for sending data from the client to the server. The data can be send typed or not and the command can wait or not for an answer. During waiting the tcl event-loop is still able to work on message-queue or tcl events. The token argument is a 4 byte character string identifying the service called on the server. The valid options are:

-wait

Send data and wait for an answer using an transaction. (default: no wait)

-type

Send data using a type prefix for every argument arg. Valid type prefixes are: -int (integer), -wid (wide integer), -dbl (double), -str (string), -bin (binary data) and -lst (list data). (default: no type)

-timeout SEC

Don’t -wait more than SEC seconds to get and answer from the server. If no answer is available an error is raised. (default: 900sec)

$context read ?-type?

The read command is used to return all items of the message-queue package as a tcl list. If the option -type was specified every item is prefixed by the same type identifier as mentioned in $context send -type. (default: no type prefix)

$context next ?option? ?type|-all?

The next command is used to return the next item of the message-queue package. If no item is available an error is raised. The type argument is used to specify the exact type to retrieve or -all if every type is allowed and has the same syntax as used in the $context send -type option. If the exact type is not available an error is raised. The valid options are:

-undo

Undo the last "$context next" command and put the data back into the package. Only one undo level is supported directly after a "$context next" command.

-type

Add type prefix to the item returned, same syntax as the $context send -type command. (default: no type)

-numItems

Return the number of items available in the current message-queue package ready to retrieve.

while {[$context next -numItems]} {
  set myInt [$context next -int]
  ...
}

-transaction

Return a reference to the current transaction. A transaction is only valid for the current service request. If during the service request an other service have to be called the current transaction will be overwritten by the new service request. To get the right transaction for the original service request the transaction have to be stored and later added to the $context return ... command.

proc MyServiceProcForSRV1 {context} {
 ## !save! the transaction
  set trans [$context next -transaction]
  set val   [$context next -int]
 ## do some other service call and wait for the answer
  set ret   [$context send -wait SRV2 "add some data"]
 ## finish the original service call
  return [$context return -transaction $trans "return some data like $ret"]
}

$context get ?option?

The get command is used to retrieve various information’s from the message-queue object defined in the msgque create ... command. The valid options are:

debug

Return the debug level as number between 0 and 9.

binary

Return the binary mode as 1 (yes) or 0 (no).

silent

Return the silent mode as 1 (yes) or 0 (no).

type

Return the type mode as SERVER or CLIENT.

context

Return the context mode as PARENT or CHILD.

contextId

Return the contextId mode as number identifying the current context.

$context service option token ?proc?

The services command is used to create and delete services. A service have to be defined on the server to provide services to the client and is defined by a token of size 4 bytes. The functionality of a service is defined in the tcl procedure proc expecting just one argument, the context, as parameter. The creation of a service is usually done in the server-configuration procedure CONFIG of the msgque create --server --config CONFIG ... command. Creation and deletion of a service can be done during normal operation without any restriction. Calling a not existing service by a client raises an error in the client. Deleting a non existing service in the server raises an error in the server. The valid options are:

create

Create a new service for token using tcl procedure proc.

proc MyServiceProc {context} {
  ...
}
$context create SRV1 MyServiceProc

delete

Delete a service for token. If the special token _ALL is used all services are deleted.

$context return ?option option ... ?arg arg ...?

The return command is used at the end of the service procedure to return the requested information or an error if something went wrong. If an error is returned to the client, the client itself is raising an error. Errors returned are message-queue errors like "wrong data-type" or tcl errors like "wrong syntax". The valid options are:

-type

Expect a type prefix for every argument arg. Valid type prefixes are: -int (integer), -wid (wide integer), -dbl (double), -str (string), -bin (binary data) and -lst (list data). (default: no type)

-code ok|error

Return ok or error (default: ok). If the code is error an error is raised in the client using following options:

-prefix

Additional information to identify the source of the error. (default: empty)

-num

The error number, just a number identifying the error. (default: -1)

-text

The text of the error message, usually a character string. (default: empty)

-transaction

The transaction used for the return message. Use $context next -transaction for additional information’s. (Default: use the transaction of the last service call)

$context processEvent

The processEvent command is used to enter the message-queue event-loop. After this command no additional commands are processed exccept events. This command is usually the last command in a server application. The message-queue event-loop is linked with the tcl-event-loop and tcl events are processed. If the client shutdown the connection the server will shutdown too and Tcl_Exit is called.

## starting the server and enter the event-loop
[msgque create --server --config CONFIG ...] processEvent

The filter mode is related to a special usage of the tclmessage-queue software called command pipline. A command pipeline is well known from the unix shell to link different commands together to act like a single application:

command1 | command2 | command3

A command pipeline with tclmessage queues is using the special token @ to link the commands together:

msgcmd1 @ msgcmd2 @ msgcmd3

In the libmsgque distribution some commands written in C are allready available like:

asplit, acut, asort, ajoin

To create a message-queue command useable in a command pipeline two token are predefined:

_FTR

A servies token to act on filter data in a flow. Basically ever data is split into lines and every line is split into columns by the asplit executable. Every line is send using the _FTR token and the following filter commands act on the _FTR service to read, manipulate and send the data to the next filter command.

_EOF

A service token to act on the end of a filter data flow. Sometimes the filter data can not be served in a flow (example: sorting of the input lines need to read all lines befor the data can be send to the next filter command) and the _EOF service is called exact one time after all data was send.

The valid msgque create options for filters are:

--filter

Create a --server in --filter mode. This option expects additional servers after the @ command-line argument.

--FTRproc tclproc

Use the tcl procedure tclproc to serve the _FTR token.

--EOFproc tclproc

Use the tcl procedure tclproc to serve the _EOF token.

Unix

The library is available on unix like system’s using the posix system interface.

1. create a server to serve the tcl eval command and return the result

package require TclMsgque
proc Eval {ctx} {
  $ctx return -type -str [eval [$ctx next -str]]
}
proc ServerConfig {ctx} {
  $ctx service create EVAL Eval
}
[msgque create [concat --server --config ServerConfig --name MyEval $argv]] processEvent
exit 0

2. in a client call the service from 1.

package require TclMsgque
set MyCTX [msgque create @ [info nameofexecutable] MyEval.tcl]
puts [$MyCTX send -wait -type EVAL -str {info level 1}]
rename $MyCTX ""
exit 0

3. create a filter to wrap every column in a ’<>’ pair

package require TclMsgque
proc Filter {ctx} {
  set data [list]
  foreach item [$ctx read] {
    lappend data -str "<$item>"
  }
  $ctx send -type _FTR $data
}
[msgque create [concat --server --name [file tail $argv0] \
    --filter --FTRproc Filter $argv]] processEvent
exit 0

tcl(n)

tcl, unix, socket, message