Intro ===== zmq is a wrapper for the zeromq library (http://www.zeromq.org/). The wrapper is based on version 3.3 of the zeromq library. It is written using critcl 3. For a Tcl wrapper supporting other versions of zmq, check the different branches of the tclzmq repository at: https://github.com/jdc8/tclzmq 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 tclzmq, 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 (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. Building ======== Requirements: - 0MQ 3.1.0 distribution from http://download.zeromq.org/ or git repository at https://github.com/zeromq/libzmq When you want to link 0MQ to the Tcl package statically on Linux, make sure to set the CFLAGS and CXXFLAGS environment variables to -fPIC before running configure. - Tcl 8.5 or 8.6 - Critcl 3 On linux and windows: - run "tclsh build.tcl" The script searches for critcl and zeromq installation or sources. Type "tclsh build.tcl --help" for more information. On Linux, the package can be linked against 0MQ statically or dynamicallly. Default is dynamic. Use the -static option to choose static linking. On Windows, the package can also be linked against 0MQ statically or dynamicallly. Build 0MQ as a DLL to link dynamically, build it as a static library to link statically. More information on building 0MQ as a static library on Windows can be found here: http://lists.zeromq.org/pipermail/zeromq-dev/2011-September/013150.html Usage ===== Loading ------- package require zmq 3.1 Context ------- Create a context: zmq context ?<context_name>? ?-iothreads <io_threads>? This will create a zeromq context and a Tcl command with the specified <context_name> to interact with it. If no <context_name> is specified, a unique name is generated. The name of the command is returned. Context methods: <context_name> destroy <context_name> get <option> Supported options are: integer options: IO_THREADS MAX_SOCKETS list options: MONITOR <context_name> set <option> <value> Supported options are: integer options: IO_THREADS MAX_SOCKETS list options: MONITOR <context_name> term (deprecated) Socket ------ Create a socket: zmq socket ?<socket_name>? <context_name> <socket_type> This will create a zeromq socket and a Tcl command with the specified <socket_name> to interact with it. If no <socket_name> is specified, a unique name is generated. The name of the command is returned. Supported socket types are: PAIR PUB SUB REQ REP DEALER ROUTER PULL PUSH XPUB XSUB Socket methods: <socket_name> bind <endpoint> <socket_name> close <socket_name> connect <endpoint> <socket_name> disconnect <endpoint> <socket_name> get <option_name> <socket_name> getsockopt <option_name> Supported option names are: integer options: SNDHWM RCVHWM TYPE LINGER RECONNECT_IVL RECONNECT_IVL_MAX BACKLOG RCVMORE RATE SNDBUF RCVBUF RECOVERY_IVL MULTICAST_HOPS RCVTIMEO SNDTIMEO IPV4ONLY TCP_KEEPALIVE TCP_KEEPALIVE_CNT TCP_KEEPALIVE_IDLE TCP_KEEPALIVE_INTVL DELAY_ATTACH_ON_CONNECT unsigned 64 bit integer options: AFFINITY signed 64 bit integer options: MAXMSGSIZE binary options: IDENTITY LAST_ENDPOINT list options: EVENTS (returns list of POLLIN, POLLOUT or POLLERR) <socket_name> readable ?<command>? <socket_name> recv_msg <message_name> ?<flags>? Supported flags are: DONTWAIT NOBLOCK SNDMORE <socket_name> send_msg <message_name> ?<flags>? Supported flags are: DONTWAIT NOBLOCK SNDMORE <socket_name> dump <socket_name> recv ?<flags>? Supported flags are: DONTWAIT NOBLOCK SNDMORE <socket_name> send <data> ?<flags>? Supported flags are: DONTWAIT NOBLOCK SNDMORE <socket_name> sendmore <data> ?<flags>? Supported flags are: DONTWAIT NOBLOCK SNDMORE <socket_name> set <option_name> <value> ?<size>? <socket_name> setsockopt <option_name> <value> ?<size>? Supported option names are: integer options: HWM SNDHWM RCVHWM LINGER RECONNECT_IVL RECONNECT_IVL_MAX BACKLOG RATE RECOVERY_IVL SNDBUF RCVBUF MULTICAST_HOPS RCVTIMEO SNDTIMEO IPV4ONLY FAIL_UNROUTABLE TCP_KEEPALIVE TCP_KEEPALIVE_CNT TCP_KEEPALIVE_IDLE TCP_KEEPALIVE_INTVL DELAY_ATTACH_ON_CONNECT unsigned 64 bit integer options: AFFINITY signed 64 bit integer options: MAXMSGSIZE binary options: IDENTITY SUBSCRIBE UNSUBSCRIBE TCP_ACCEPT_FILTER <socket_name> unbind <endpoint> <socket_name> writable ?<command>? Message ------- Create a message: zmq message ?<message_name>? ?-data <data>? ?-size <size>? This will create a zeromq message and a Tcl command with the specified <message_name> to interact with it. If no <message_name> is specified, a unique name is generated. The name of the command is returned. Message methods: <message_name> close <message_name> copy <destination_message_name> <message_name> data <message_name> get <option> Supported options are: MORE <message_name> more <message_name> move <destination_message_name> <message_name> recv ?<flags>? Supported flags are: SNDMORE DONTWAIT <message_name> send <data> ?<flags>? Supported flags are: SNDMORE DONTWAIT <message_name> sendmore <data> ?<flags>? Supported flags are: SNDMORE DONTWAIT <message_name> set <option> <value> Supported options are: (none) <message_name> size <message_name> dump Helper functions: zmsg recv <socket> zmsg send <socket> <message> zmsg unwrap <messageVariable> zmsg wrap <message> <data> zmsg push <message> <data> zmsg pop <messageVariable> zmsg add <message> <data> zmsg dump <message> Polling ------- Poll zermq sockets: zmq poll <poll_set> <timeout> ?<timeout_unit>? A <poll_set> is specified as a list of lists of: <socket_name> list of polling flags Supported polling flags are: POLLIN POLLOUT POLLERR Possible timeout units are: s : seconds ms : milliseconds (default) us : microseconds (will be removed for zmq 3.1) Device ------ Start a built-in device: zmq device <device_type> <in_socket_name> <out_socket_name> Supported devices are: STREAMER FORWARDER QUEUE Other commands -------------- zmq version zmq errno zmq strerror <errnum> zmq max_block_time <max_block_time_in_micro_seconds>