Guidelines for ØMQ bindings

Introduction

This document is intended to define generic guidelines and best practices for designing ØMQ API in different languages. By adhering to this specification all the APIs will have similar feel and it will be easier for developers to switch from one language to another. Also, communication between developers in different languages will be facilitated by common reference framework.

This specification doesn't deliberately specify the coding style, syntax or programming constructs to use. Each API should attempt to make these as conforming to common practice in the particular language as possible.

Some examples:

Name formatting should be chosen according to common practice in the particular language: lower-case with underscores, camel-case etc.
Objects should be used in OO languages. Functions should be used in functional languages. Etc.
Message BLOB should be accessible by a common method to manipulate BLOBs in the particular language.
Binding may expose APIs for serialisation support native to the language.

Recommended names are to be used only if needed. For instance, if language allows to return a value from the function directly, the name of the output parameter doesn't have to be used.

Binding Name

Please use the style language abbreviation + zmq.

Namespace

Each language extension should make the best effort to prevent name collisions with unrelated libraries.

For example, non-object-oriented languages can use prefixes to avoid name collisions (zmq_send). Object-oriented languages can achieve similar effect by using classes and/or namespaces (ZMQ::Send).

Preferred name of the object/namespace/prefix is "zmq". Note that it is an acronym for "zero message queueing" thus camel case variant is "ZMQ" rather than "Zmq".

Constants

ØMQ defines a rather broad set of numeric constants. For brevity's sake bindings should define these constants directly within "zmq" namespace rather them pushing them deeper into the object hierarchy.

Examples: ZMQ_REQ, ZMQ::REQ, ZMQ.REQ etc.

As these constants are the main extensibility mechanism for ØMQ, developer of the binding should make it as easy as possible to add new constants to the set.

Objects

While particular language may not be object-oriented, conceptually ØMQ provides couple of distinct "object" types.

Context

Context object represents ØMQ instance. If at all possible, developer of the binding should ensure that ØMQ can be instantiated multiple times within a single process (beware of global variables etc.) to prevent unexpected behaviour when several components, each using ØMQ, are loaded into a single process.

There should be an explicit way to create and destroy the context. Object-oriented languages can provide the functionality via constructor and destrcutor of Context object, while non-OO languages can use functions called init and term respectively. If the language has no support for destructors (e.g. Java) there should be a term function available to explicitly terminate the context.

init

name	type	default
io threads	integer

Returns newly created context.

term

No parameters, no return value.

Sockets

ØMQ sockets can be created and destroyed. Socket creation is realised using socket function of the context object. Socket destruction can be realised using socket object destructor or via the dedicated close function. If the language has no support for destructors (e.g. Java) there should be an explicit close function available.

Socket types are a primary ØMQ extension mechanism. Individual language bindings should therefore be agnostic about socket types (except for defining appropriate constants). In other words, there should be a single socket class with a single set of functions even though some of the functions may return "not implemented" error for a particular ØMQ socket type.

socket

This function is a member of 'context' class.

name	type	default
type	integer

Returns newly created socket.

close

No parameters, no return value.

setsockopt

name	type	default
option	integer
value	any

No return value.

getsockopt

name	type	default
option	integer

Returns value of the specified option.

bind

name	type	default
address	string

No return value.

connect

name	type	default
address	string

No return value.

send

name	type	default
message	message
flags	bitfield	0

Function may return a boolean value indicating whether message was sent or not (in case of non-blocking send) instead of indicating the failure via error.

recv

name	type	default
flags	bitfield	0

Function returns the message received. Language binding can choose more convenient way to report failure to fetch a message (in case of non-blocking recv) instead of raising error (e.g. returning nil).