gk::rpc listen ?-port port?
gk::rpc connect host port
gk::rpc send ?-class class? sock message
gk::rpc atclose sock cmd
gk::rpc active
gk::rpc hostport sock
gk::rpc handler sock class ?cmd?
gk::rpc handler default ?cmd?
The gk::rpc command is used internally within GroupKit, and provides a higher-level interface on top of the standard Tcl socket facilities. In particular, the gk::rpc command provides for bi-directional channels over which Tcl commands can be sent, reuses existing socket connections where possible, and allows flexible handling of received messages.The "gk::rpc listen" command is used to setup a listening socket that other processes can connect to; this must be the first gk::rpc command invoked. You can optionally specify a port to listen on, otherwise an unused port is selected. This command returns the port that the socket is listening on.
The "gk::rpc connect" command opens a socket connection to another process that has previously set up a listener with "gk::rpc listen". A socket identifier is returned that can be used to send messages over the socket. If an existing connection to the external process has already been made, a new socket is not created but the existing identifier is returned.
The "gk::rpc send" command sends a message over a socket. The optional "class" argument can be used to specify the type of message, which the handler mechanism (described below) can take advantage of. The message itself is a single string, typically containing a Tcl command to be evaluated.
The "gk::rpc atclose" command arranges for a particular Tcl command to be executed when a particular socket is closed.
During the scope of handling a received message, the "gk::rpc active" command will return the socket identifier from which the message was sent. When no message is currently being handled, this command returns an error.
The "gk::rpc hostport" command returns a two item list, containing the host and port of the indicated socket. Note that the port is actually the port of the remote processes' listener, rather than the actual port for this connection.
The "gk::rpc handler" mechanism allows you to define how incoming messages are handled. By default, all incoming messages are evaluated as Tcl commands. You may instead choose to install your own routine, which will be called whenever a message of the indicated class comes in on a given socket. The "default" option lets you provide a global handler, which is a fallback for when a specific handler for a class and socket is not provided. Omitting the "cmd" parameter on either of these forms will return the current handler.