search

jdc8 / tclzmq

Tcl wrapper for zeromq
Other
14 stars 6 forks source link

readme

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:

On linux and windows:

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>