zmq - Zmq Package Reference
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 3.3 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.
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:
The zmq wrapper will lappend the following data to the specified monitor callback command before calling it in case of monitor events:
context
socket
event flag
event data
Known event flags are:
Destroy the ZeroMQ context and delete the associated Tcl object command.
Get context option. See configure method for list of supported options.
Set context option. See configure method for list of supported options.
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:
Accept connections on a socket for specified endpoint.
Get socket option. See configure method for list of supported options.
See destroy method.
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:
Connect to a socket on the specified endpoint.
Close the ZeroMQ socket and delete the associated Tcl object command.
Disconnect from a socket on the specified endpoint.
Read message from the socket and return it in human readable debug format.
Get socket option. See configure method for list of supported options.
If specified set, or if not specified get, the socket readable callback command.
Read a message part from the socket and return it as a string. Only the DONTWAIT flag is supported.
Read a message part from the socket and place it in the specified message object. Only the DONTWAIT flag is supported.
Send the specified data to the socket as message part. Supported flags are DONTWAIT and SNDMORE.
Send the message part in the specified message object to the socket. Supported flags are DONTWAIT and SNDMORE.
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.
Set socket option. See configure method for list of supported options.
Stop accepting connections on a socket for the specified endpoint.
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.
Get message option. See configure method for list of supported options.
See destroy method.
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:
Copy the message to the specified message.
Get the message data as a (binary) string.
Close the ZeroMQ message and delete the associated Tcl object command.
Get the message as a human readable string.
Get message option. See configure method for list of supported options.
Get indication if more messages are to be received as part of a multi part message.
Move contents to the specified message.
Receive a message on the specified socket. Only the DONTWAIT flag is supported.
Send a message to the specified socket as message part. Supported flags are DONTWAIT and SNDMORE.
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.
Set message option. See configure method for list of supported options.
Return the size of the message data part.
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.
Add a message part to a multi-part message. The updated multi-part message is returned.
Return the multi-part message in a human readable form.
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.
Push a message part to the beginning of a multi-part message. The modified multi-part message is returned.
Receive a multi-part message on the specified socket. The received message is returned.
Send a multi-part message to the specified socket.
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.
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.
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:
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.
Start a built-in ZeroMQ device. Known devices are:
Return the ZeroMQ version used by the Tcl wrapper.
Return the last returned ZeroMQ error code.
Return the human readable string for a ZeroMQ error code.
Set maximum blocking time for the Tcl event loop waiting for ZeroMQ event in micro seconds. Default is 1000 micro seconds.
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 proc monitor {context socket event data} { puts "Monitor callback: context=$context, socket=$socket, event=$event, data=$data" } # Prepare our context and publisher zmq context context context configure MONITOR monitor 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
More Tcl example can be found in the ZeroMQ Guide.
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.
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.
RPC, broadcast, communication, inter process communication, message queue, messaging, producer - consumer, publish - subscribe, queue
Messaging
Copyright © Jos Decoster <jos.decoster@gmail.com>