Name

zmq - Zmq Package Reference

Table Of Contents

• Table Of Contents
• Synopsis
• Description
• Contexts
  • Context PACKAGE COMMANDS
  • Context OBJECT METHODS
• Sockets
  • Socket PACKAGE COMMANDS
  • Socket OBJECT METHODS
• Messages
  • Message PACKAGE COMMANDS
  • Message OBJECT METHODS
• Multi-part message helper functions
• Polling
• Devices
• Miscellaneous
• Examples
• Bugs, ideas, feedback
• License
• Keywords
• Category
• Copyright

Synopsis

Description

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.

Contexts

Sockets

Messages

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 add messageList data

Add a message part to a multi-part message. The updated multi-part message is returned.

zmsg dump messageList

Return the multi-part message in a human readable form.

zmsg pop messageListName

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 push messageList data

Push a message part to the beginning of a multi-part message. The modified multi-part message is returned.

zmsg recv socketName

Receive a multi-part message on the specified socket. The received message is returned.

zmsg send socketName messageList

Send a multi-part message to the specified socket.

zmsg unwrap messageListName

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 wrap messageList data

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 poll pollList timeout ?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:

1. socket

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

Devices

zmq device deviceType inputSocketName outputSocketName

Start a built-in ZeroMQ device. Known devices are:

FORWARDER

QUEUE

STREAMER

Miscellaneous

zmq version

Return the ZeroMQ version used by the Tcl wrapper.

zmq errno

Return the last returned ZeroMQ error code.

zmq strerror errorNumber

Return the human readable string for a ZeroMQ error code.

zmq max_block_time blockTime

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

Bugs, ideas, feedback

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

Category

Messaging

Copyright

Copyright © Jos Decoster <jos.decoster@gmail.com>