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>