The zmq package is a wrapper for the ZeroMQ library. ZeroMQ can be found at http://www.zeromq.org . The wrapper is based on version 4.0.1 of the ZeroMQ library. The package is written using critcl 3. Use this documentation in combination with the ZeroMQ documentation for more details. All sockets in this documentation refer to ZeroMQ sockets. The ZeroMQ API use set and get functions to set or get context, socket and message options. This wrapper provides set and get methods for contexts, sockets and message for compatibility with the ZeroMQ API but also provides the more Tcl style cget and configure methods. The ZeroMQ API uses destroy for contexts and close for sockets and messages. This wrapper provides the same methods for compatibility with the ZeroMQ API but also provides a destroy method for sockets and messages.
This command creates a new ZeroMQ context object and associated Tcl object command whose name is contextName if specified or auto generated if not specified. The object command will be created under the current namespace if the contextName is not fully qualified, and in the specified namespace otherwise. The object command name is returned by this command. The object command methods are explained in section Context OBJECT METHODS.
Context OBJECT METHODS
contextNamecgetoptionName
Get context option. See configure method for list of supported options.
Query or modify context options. If no option is specified, returns a list describing all of the available options. If option is specified with no value, then the command returns the value for the specified option. If one or more option-value pairs are specified, then the command modifies the given context option(s) to have the given value(s); in this case the command returns an empty string. Supported options with associated data type are:
IO_THREADS
integer
MAX_SOCKETS
integer
contextNamedestroy
Destroy the ZeroMQ context and delete the associated Tcl object command.
contextNamegetoptionName
Get context option. See configure method for list of supported options.
contextNamesetoptionNameoptionValue
Set context option. See configure method for list of supported options.
Sockets
Socket PACKAGE COMMANDS
zmq socket ?socketName? contextNamesocketType
This command creates a new ZeroMQ socket object and associated Tcl object command whose name is socketName if specified or auto generated if not specified within the specified context and of the specified type. The object command will be created under the current namespace if the socketName is not fully qualified, and in the specified namespace otherwise. The object command name is returned by this command. The object command methods are explained in section Socket OBJECT METHODS. Valid values for socketType are:
DEALER
PAIR
PUB
PULL
PUSH
REP
REQ
ROUTER
STREAM
SUB
XPUB
XSUB
Socket OBJECT METHODS
socketNamebindendPoint
Accept connections on a socket for specified endpoint.
socketNamecgetoptionName
Get socket option. See configure method for list of supported options.
Query or modify socket options. If no option is specified, returns a list describing all of the available options. If option is specified with no value, then the command returns the value for the specified option. If one or more option-value pairs are specified, then the command modifies the given socket option(s) to have the given value(s); in this case the command returns an empty string. Supported options with associated data type are:
AFFINITY
unsigned wide integer
BACKLOG
integer
EVENTS
list of poll flags: POLLIN, POLLOUT or POLLERR
ROUTER_MANDATORY
integer, write-only
IDENTITY
binary
IMMEDIATE
integer
LAST_ENDPOINT
binary, read-only
LINGER
integer
MAXMSGSIZE
wide integer
MECHANISM
enum: NULL, PLAIN, or CURVE, read-only
MULTICAST_HOPS
integer
RATE
integer
RCVBUF
integer
RCVHWM
integer
RCVMORE
integer, read-only
RCVTIMEO
integer
RECONNECT_IVL
integer
RECONNECT_IVL_MAX
integer
RECOVERY_IVL
integer
ROUTER_MANDATORY
integer, write-only
SNDBUF
integer
SNDHWM
integer
SNDTIMEO
integer
SUBSCRIBE
binary, write-only
TCP_ACCEPT_FILTER
string, write-only
TCP_KEEPALIVE
integer
TCP_KEEPALIVE_CNT
integer
TCP_KEEPALIVE_IDLE
integer
TCP_KEEPALIVE_INTVL
integer
TYPE
integer
UNSUBSCRIBE
binary, write-only
XPUB_VERBOSE
integer, write-only
PLAIN_SERVER
integer
PLAIN_USERNAME
string
PLAIN_PASSWORD
string
CURVE_SERVER
integer
CURVE_PUBLICKEY
string
CURVE_SECRETKEY
string
CURVE_SERVERKEY
string
PROBE_ROUTER
integer
REQ_CORRELATE
integer
REQ_RELAXED
integer
CONFLATE
integer, write-only
ZAP_DOMAIN
string
IPV6
integer
socketNameconnectendPoint
Connect to a socket on the specified endpoint.
socketNamedestroy
Close the ZeroMQ socket and delete the associated Tcl object command.
socketNamedisconnectendPoint
Disconnect from a socket on the specified endpoint.
socketNamedump
Read message from the socket and return it in human readable debug format.
socketNamegetoptionName
Get socket option. See configure method for list of supported options.
socketNamemonitorendPoint ?eventsList?
Arrange for monitoring the specified events. If no events are specified, all events are monitored. Monitoring information is available on a socket of type PAIR on the specified end-point. Known events can be found in Socket monitoring
socketNamereadable ?command?
If specified set, or if not specified get, the socket readable callback command.
socketNamerecv ?flagsList?
Read a message part from the socket and return it as a string. Only the DONTWAIT flag is supported.
socketNamerecv_monitor_event
Read a monitor event part from the monitor socket and return it as a dictionary. The socket must be of type PAIR and must be connected to the end-point passed to the socket monitor command. The dictionary will contain the triggered event and extra information depending on the triggered event (e.g address, error code, ...). More infomation about monitoring and possible events can be found in Socket monitoring.
socketNamerecv_msgmessage ?flagsList?
Read a message part from the socket and place it in the specified message object. Only the DONTWAIT flag is supported.
socketNamesenddata ?flagsList?
Send the specified data to the socket as message part. Supported flags are DONTWAIT and SNDMORE.
socketNamesend_msgmessage ?flagsList?
Send the message part in the specified message object to the socket. Supported flags are DONTWAIT and SNDMORE.
socketNamesendmoredata ?flagsList?
Send the specified data to the socket as message part and indicate there are more message parts to come. Supported flags are DONTWAIT and SNDMORE.
socketNamesetoptionNameoptionValue ?optionSize?
Set socket option. See configure method for list of supported options.
socketNameunbindendPoint
Stop accepting connections on a socket for the specified endpoint.
socketNamewritable ?command?
If specified set, or if not specified get, the socket writable callback command.
This command creates a new ZeroMQ message object and associated Tcl object command whose name is messageName if specified or auto generated if not specified with specified size and data. The object command will be created under the current namespace if the messageName is not fully qualified, and in the specified namespace otherwise. The object command name is returned by this command. The object command methods are explained in section Message OBJECT METHODS. The use of this message type is not needed with the wrapper. Check the Socket OBJECT METHODS for socket commands directly reading and writing string and Message helper functions for utility functions to read and write strings.
Message OBJECT METHODS
messageNamecgetoptionName
Get message option. See configure method for list of supported options.
Query or modify message options. If no option is specified, returns a list describing all of the available options. If option is specified with no value, then the command returns the value for the specified option. If one or more option-value pairs are specified, then the command modifies the given message option(s) to have the given value(s); in this case the command returns an empty string. Supported options with associated data type are:
MORE
integer, read-only
messageNamecopydestinationMessageName
Copy the message to the specified message.
messageNamedata
Get the message data as a (binary) string.
messageNamedestroy
Close the ZeroMQ message and delete the associated Tcl object command.
messageNamedump
Get the message as a human readable string.
messageNamegetoptionName
Get message option. See configure method for list of supported options.
messageNamemore
Get indication if more messages are to be received as part of a multi part message.
messageNamemovedestinationMessageName
Move contents to the specified message.
messageNamerecvsocketName ?flagsList?
Receive a message on the specified socket. Only the DONTWAIT flag is supported.
messageNamesendsocketName ?flagsList?
Send a message to the specified socket as message part. Supported flags are DONTWAIT and SNDMORE.
messageNamesendmoresocketName ?flagsList?
Send a message to the specified socket as message part and indicate there are more parts to come as part of a multi part message. Supported flags are DONTWAIT and SNDMORE.
messageNamesetoptionNameoptionValue
Set message option. See configure method for list of supported options.
messageNamesize
Return the size of the message data part.
Multi-part message helper functions
ZeroMQ sends multi-part messages (e.g. when using envelopes). These helper functions can be used to make it easier to handle those. Data is specified as a (binary) string. A multi-part message is specified a a list of (binary) strings.
zmsg addmessageListdata
Add a message part to a multi-part message. The updated multi-part message is returned.
zmsg dumpmessageList
Return the multi-part message in a human readable form.
zmsg popmessageListName
Pop a message part from the beginning of the specified multi-part message. The popped message part is returned and the specified multi-part message is modified.
zmsg pushmessageListdata
Push a message part to the beginning of a multi-part message. The modified multi-part message is returned.
zmsg recvsocketName
Receive a multi-part message on the specified socket. The received message is returned.
zmsg sendsocketNamemessageList
Send a multi-part message to the specified socket.
zmsg unwrapmessageListName
Unwrap multi-part message. The unwrapped message part is returned. An empty message-part following the unwrapped message part (e.g as part of an envelope) is also removed.
zmsg wrapmessageListdata
Wrap the multi-part message with the specified data. An empty message part is inserted between the specified data and the spoecified multi-part message.
Polling
zmq pollpollListtimeout ?timeoutUnit?
Poll the specified sockets for the specifed events. A maximum timeout must be specified. If the value of timeout is 0, the command returns immediately. If the value of timeout is -1, the command will block indefinitely until a specified event occurs. The polling list if specified as a list of poll requests. Such a poll request is a list of:
socket
list of event flags Supported event flags are:
POLLIN
POLLOUT
The poll command will return a list in the same format as the input polling list with list items for each item in the original list for which an event occured and in the list of event flags the events which occured.
Helper function for monitoring socket events. This function is a wrapper for the socket monitor and socket recv_monitor_event commands. The event dictionary as read with the socket recv_monitor_event is lappended to the callback-command and the callback command is executed each time one of the specified events is triggered for the specified socket. The event-loop must be executed in order to be able to receive monitoring callback in this way. Supported events for monitoring are:
ACCEPTED
ACCEPT_FAILED
ALL
BIND_FAILED
CLOSED
CLOSE_FAILED
CONNECTED
CONNECT_DELAYED
CONNECT_RETRIED
DISCONNECTED
LISTENING
Miscellaneous
zmq version
Return the ZeroMQ version used by the Tcl wrapper.
zmq errno
Return the last returned ZeroMQ error code.
zmq strerrorerrorNumber
Return the human readable string for a ZeroMQ error code.
zmq max_block_timeblockTime
Set maximum blocking time for the Tcl event loop waiting for ZeroMQ event in micro seconds. Default is 1000 micro seconds.
Examples
A weather data publishing server, also found in the ZeroMQ Guide :
#
# Weather update server
# Binds PUB socket to tcp:#*:5556
# Publishes random weather updates
#
package require zmq
# Prepare our context and publisher
zmq context context
zmq socket publisher context PUB
publisher bind "tcp://*:5556"
if {$::tcl_platform(platform) ne "windows"} {
publisher bind "ipc://weather.ipc"
}
# Initialize random number generator
expr {srand([clock seconds])}
while {1} {
# Get values that will fool the boss
set zipcode [expr {int(rand()*100000)}]
set temperature [expr {int(rand()*215)-80}]
set relhumidity [expr {int(rand()*50)+50}]
# Send message to all subscribers
set data [format "%05d %d %d" $zipcode $temperature $relhumidity]
if {$zipcode eq "10001"} {
puts $data
}
zmq message msg -data $data
publisher send_msg msg
msg destroy
update idletasks
}
publisher destroy
context destroy
And the corresponding client:
#
# Weather update client
# Connects SUB socket to tcp:#localhost:5556
# Collects weather updates and finds avg temp in zipcode
#
package require zmq
# Socket to talk to server
zmq context context
zmq socket subscriber context SUB
subscriber connect "tcp://localhost:5556"
# Subscribe to zipcode, default is NYC, 10001
if {[llength $argv]} {
set filter [lindex $argv 0]
} else {
set filter "10001"
}
subscriber setsockopt SUBSCRIBE $filter
# Process updates
set total_temp 0
for {set update_nbr 0} {$update_nbr < 10} {incr update_nbr} {
zmq message msg
subscriber recv_msg msg
lassign [msg data] zipcode temperature relhumidity
puts [msg data]
msg close
incr total_temp $temperature
}
puts "Averate temperatur for zipcode $filter was [expr {$total_temp/$update_nbr}]F"
subscriber destroy
context destroy
Or the client rewritten to process the messages from the publisher asynchronously:
#
# Weather update client
# Connects SUB socket to tcp:#localhost:5556
# Collects weather updates and finds avg temp in zipcode
#
package require zmq
# Socket to talk to server
zmq context context
zmq socket subscriber context SUB
subscriber connect "tcp://localhost:5556"
# Subscribe to zipcode, default is NYC, 10001
if {[llength $argv]} {
set filter [lindex $argv 0]
} else {
set filter "10001"
}
proc get_weather {} {
global total_temp cnt done
set data [subscriber recv]
puts $data
lassign $data zipcode temperature relhumidity
incr total_temp $temperature
incr cnt
if {$cnt >= 10} {
set done 1
}
}
subscriber setsockopt SUBSCRIBE $filter
set total_temp 0
set cnt 0
subscriber readable get_weather
# Process updates
vwait done
puts "Averate temperatur for zipcode $filter was [expr {$total_temp/$cnt}]F"
subscriber destroy
context destroy
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such at the Github tracker . Please also report any ideas for enhancements you may have for either package and/or documentation.
License
zmq uses different licenses for different parts of the code. The 'core' of zmq (located in zmq.tcl) is licensed under LGPLv3. This just means that if you make any changes to how that code works, you must release those changes under the LGPL. If you just use zmq, then you can use any license you want for your own code. Check COPYING.LESSER for more info. The restrictions imposed by the LGPL make no sense for the 'non-core' functionality in zmq (derivative code must also be LGPL or GPL), especially for examples, so all 'non-core' code is relicensed under the more permissive BSD license (specifically Modified BSD aka New BSD aka 3-clause BSD), where possible. This means that you can copy this code and build your own apps without needing to license your own code with the LGPL or GPL. Check COPYING.BSD for more info.
KEYWORDS
RPC, broadcast, communication, inter process communication, message queue, messaging, producer - consumer, publish - subscribe, queue
A publishing example, also found in the ØMQ Guide :
#
# Weather update server
# Binds PUB socket to tcp:#*:5556
# Publishes random weather updates
#
package require zmq
# Prepare our context and publisher
zmq context context
zmq socket publisher context PUB
publisher bind "tcp://*:5556"
publisher bind "ipc://weather.ipc"
# Initialize random number generator
expr {srand([clock seconds])}
while {1} {
# Get values that will fool the boss
set zipcode [expr {int(rand()*100000)}]
set temperature [expr {int(rand()*215)-80}]
set relhumidity [expr {int(rand()*50)+50}]
# Send message to all subscribers
set data [format "%05d %d %d" $zipcode $temperature $relhumidity]
if {$zipcode eq "10001"} {
puts $data
}
zmq message msg -data $data
publisher send_msg msg
msg close
}
publisher close
context term
with corresponding client:
#
# Weather update client
# Connects SUB socket to tcp:#localhost:5556
# Collects weather updates and finds avg temp in zipcode
#
package require zmq
# Socket to talk to server
zmq context context
zmq socket subscriber context SUB
subscriber connect "tcp://localhost:5556"
# Subscribe to zipcode, default is NYC, 10001
if {[llength $argv]} {
set filter [lindex $argv 0]
} else {
set filter "10001"
}
subscriber setsockopt SUBSCRIBE $filter
# Process 100 updates
set total_temp 0
for {set update_nbr 0} {$update_nbr < 100} {incr update_nbr} {
zmq message msg
subscriber recv_msg msg
lassign [msg data] zipcode temperature relhumidity
puts [msg data]
msg close
incr total_temp $temperature
}
puts "Averate temperatur for zipcode $filter was [expr {$total_temp/$update_nbr}]F"
subscriber close
context term
Rewriting the client to process the messages from the publisher asynchronously:
#
# Weather update client
# Connects SUB socket to tcp:#localhost:5556
# Collects weather updates and finds avg temp in zipcode
#
package require zmq
# Socket to talk to server
zmq context context
zmq socket subscriber context SUB
subscriber connect "tcp://localhost:5556"
# Subscribe to zipcode, default is NYC, 10001
if {[llength $argv]} {
set filter [lindex $argv 0]
} else {
set filter "10001"
}
proc get_weather {} {
global total_temp cnt done
set data [subscriber recv]
puts $data
lassign $data zipcode temperature relhumidity
incr total_temp $temperature
incr cnt
if {$cnt >= 10} {
set done 1
}
}
subscriber setsockopt SUBSCRIBE $filter
set total_temp 0
set cnt 0
subscriber readable get_weather
# Process 100 updates
vwait done
puts "Averate temperatur for zipcode $filter was [expr {$total_temp/$cnt}]F"
subscriber close
context term
I guess so. All ZeroMQ commands are wrapped and most of the examples are ported to Tcl. Still work to do to make the package thread safe and to improve the asynchronous processing of messages.