Ciao bindings for ZeroMQ messaging library

Author(s): Dragan Ivanovic (idragan@clip.dia.fi.upm.es).

Access to the basic ZMQ functionality from Ciao Prolog

Documentation on exports

PREDICATE

Usage:

  • Description: Initializes the ZMQ context for the current thread. This is done automatically on any call to ZMQ routines that require the context.
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage:

  • Description: Terminates the ZMQ context for the current thread. Previously attempts to close all open sockets.
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_socket(SocketAtom,TypeAtom)

  • Description: Creates a new socket named by atom SocketAtom. TypeAtom corresponds to a ZMQ socket type. It can be one of: req, rep, pub, sub, push, pull, pair, router, dealer. No other socket must be associated with SocketAtom at the time of calling.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:atm/1)TypeAtom is an atom.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)TypeAtom is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)TypeAtom is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_close(SocketAtom)

  • Description: Closes socket identified with the atom SocketAtom.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_bind(SocketAtom,Endpoint)

  • Description: Binds socket SocketAtom to the given Endpoint address. Addresses are strings of the form “tcp://HOST:PORT”, or “ipc://ENDPOINT”, or “inproc://IDENTIFIER”. See ZMQ documentation for more details. A socket can be simultaneously bound to several endpoints.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:string/1)Endpoint is a string (a list of character codes).
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Endpoint is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Endpoint is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_connect(SocketAtom,Endpoint)

  • Description: Connects socket to the given endpoint. See zmq_bind/2 for more details. A socket can be simultaneously connected to several endpoints.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:string/1)Endpoint is a string (a list of character codes).
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Endpoint is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Endpoint is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_subscribe(SocketAtom,Len,Prefix)

  • Description: Subscribes socket SocketAtom of type sub to listen for messages that start with the given Prefix byte list of size Len. A sub socket must be subscribed to receive messages, even if the prefix is an empty list. If Size<0, the actual size will be the length of Prefix, otherwise at most Size bytes from Prefix will be used. If Size>length(Prefix), the remaining bytes will be zeroes.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:int/1)Len is an integer.
    (foreign_interface_properties:any_term/1)Prefix is any term. The foreign interface passes it to C functions as a general term.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Len is currently ground (it contains no variables).
    (term_typing:ground/1)Prefix is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Len is currently ground (it contains no variables).
    (term_typing:ground/1)Prefix is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_unsubscribe(SocketAtom,Len,Prefix)

  • Description: Removes subscription previously established with zmq_subscribe/3. If Size<0, the actual size will be the length of Prefix, otherwise at most Size bytes from Prefix will be usedP. If Size>length(Prefix), the remaining bytes will be zeroes.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:int/1)Len is an integer.
    (foreign_interface_properties:any_term/1)Prefix is any term. The foreign interface passes it to C functions as a general term.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Len is currently ground (it contains no variables).
    (term_typing:ground/1)Prefix is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Len is currently ground (it contains no variables).
    (term_typing:ground/1)Prefix is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_send(SocketAtom,Size,ByteList,Options)

  • Description: Sends a list of bytes ByteList of size Size over socket SocketAtom using the list of options Options. Possible options are: noblock to send in background, and sndmore to signify that more message parts will follow. If Size<0, the actual size will be the length of ByteList, otherwise at most Size bytes from ByteList will be used. If Size>length(ByteList), the remaining bytes will be zeroes.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:int/1)Size is an integer.
    (foreign_interface_properties:any_term/1)ByteList is any term. The foreign interface passes it to C functions as a general term.
    (foreign_interface_properties:any_term/1)Options is any term. The foreign interface passes it to C functions as a general term.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Size is currently ground (it contains no variables).
    (term_typing:ground/1)ByteList is currently ground (it contains no variables).
    (term_typing:ground/1)Options is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Size is currently ground (it contains no variables).
    (term_typing:ground/1)ByteList is currently ground (it contains no variables).
    (term_typing:ground/1)Options is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_recv(SocketAtom,Maybe,Size,ByteList,Options)

  • Description: Reads a message (or a message part) from socket SocketAtom using list of options Options. The only valid option is currently noblock, which returns without waiting for a message to arrive. On exit, Maybe is set to either none (if no message was read), or to some if some message (part) was read. Size tells the number of bytes read, and ByteList is the list of bytes read.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (foreign_interface_properties:any_term/1)Maybe is any term. The foreign interface passes it to C functions as a general term.
    (basic_props:int/1)Size is an integer.
    (foreign_interface_properties:byte_list/1)ByteList is a list of bytes.
    (foreign_interface_properties:any_term/1)Options is any term. The foreign interface passes it to C functions as a general term.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Options is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketAtom is currently ground (it contains no variables).
    (term_typing:ground/1)Maybe is currently ground (it contains no variables).
    (term_typing:ground/1)Size is currently ground (it contains no variables).
    (term_typing:ground/1)ByteList is currently ground (it contains no variables).
    (term_typing:ground/1)Options is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.
    (foreign_interface_properties:returns/2)The result of the foreign function that implements the Prolog predicate Name is unified with the Prolog variable Maybe. Cannot be used without foreign/1 or foreign/2.
    (foreign_interface_properties:size_of/3)For predicate zmq_recv(SocketAtom,Maybe,Size,ByteList,Options), the size of the argument of type byte_list/1, ByteList, is given by the argument of type integer Size.

PREDICATE

Usage: zmq_multipart_pending(SocketName,Result)

  • Description: Checks whether there are more parts from the same multipart message waiting to be read on the socket SocketAtom. Result is set to either some or none.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)SocketName is an atom.
    (foreign_interface_properties:any_term/1)Result is any term. The foreign interface passes it to C functions as a general term.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketName is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketName is currently ground (it contains no variables).
    (term_typing:ground/1)Result is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.
    (foreign_interface_properties:returns/2)The result of the foreign function that implements the Prolog predicate Name is unified with the Prolog variable Result. Cannot be used without foreign/1 or foreign/2.

PREDICATE

Usage: zmq_poll(SocketList,Timeout,Result)

  • Description: Polls sockets from the list SocketList for incoming messages. Timeout defines how long to wait in microseconds: 0 means immediate return, and -1 means indefinite waiting. Result is a sublist of sockets from SocketList that have pending messages.
  • Calls should, and exit will be compatible with:
    (foreign_interface_properties:any_term/1)SocketList is any term. The foreign interface passes it to C functions as a general term.
    (basic_props:int/1)Timeout is an integer.
    (foreign_interface_properties:any_term/1)Result is any term. The foreign interface passes it to C functions as a general term.
  • The following properties should hold at call time:
    (term_typing:ground/1)SocketList is currently ground (it contains no variables).
    (term_typing:ground/1)Timeout is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)SocketList is currently ground (it contains no variables).
    (term_typing:ground/1)Timeout is currently ground (it contains no variables).
    (term_typing:ground/1)Result is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.
    (foreign_interface_properties:returns/2)The result of the foreign function that implements the Prolog predicate Name is unified with the Prolog variable Result. Cannot be used without foreign/1 or foreign/2.

PREDICATE

Usage: zmq_device(DevType,Frontend,Backend)

  • Description: Starts a ZMQ “device” of type DevType with front-end socket Frontend and back-end socket Backend. DevType must be queue, forwarder or streamer. The front-end and the back-end sockets must be previously set up with correct socket types and bound/connected to their respective endpoints.
  • Calls should, and exit will be compatible with:
    (basic_props:atm/1)DevType is an atom.
    (basic_props:atm/1)Frontend is an atom.
    (basic_props:atm/1)Backend is an atom.
  • The following properties should hold at call time:
    (term_typing:ground/1)DevType is currently ground (it contains no variables).
    (term_typing:ground/1)Frontend is currently ground (it contains no variables).
    (term_typing:ground/1)Backend is currently ground (it contains no variables).
  • The following properties hold upon exit:
    (term_typing:ground/1)DevType is currently ground (it contains no variables).
    (term_typing:ground/1)Frontend is currently ground (it contains no variables).
    (term_typing:ground/1)Backend is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.

PREDICATE

Usage: zmq_error_check(Maybe)

  • Description: Checks whether errors ocurred in the previous zmq_XXX operations. Maybe is set either to none or to some
  • Calls should, and exit will be compatible with:
    (foreign_interface_properties:any_term/1)Maybe is any term. The foreign interface passes it to C functions as a general term.
  • The following properties hold upon exit:
    (term_typing:ground/1)Maybe is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.
    (foreign_interface_properties:returns/2)The result of the foreign function that implements the Prolog predicate Name is unified with the Prolog variable Maybe. Cannot be used without foreign/1 or foreign/2.

PREDICATE

Usage: zmq_errors(ErrorList)

  • Description: Retrieves and clears the list of errors (latest first) that have accumulated as the result of the previous zmq_XXX calls. Each list element has the form error(Errno, Reason, Socket), where Errno is a numeric error code, Reason is an atom describing the context of the error, and Socket is the name of socket in relation to which the error has occured. For an error that has ocurred in zmq_poll/3 Socket is .
  • Calls should, and exit will be compatible with:
    (foreign_interface_properties:any_term/1)ErrorList is any term. The foreign interface passes it to C functions as a general term.
  • The following properties hold upon exit:
    (term_typing:ground/1)ErrorList is currently ground (it contains no variables).
  • The following properties hold globally:
    (foreign_interface_properties:foreign/2)The Prolog predicate PrologName is implemented using the foreign function ForeignName.
    (foreign_interface_properties:returns/2)The result of the foreign function that implements the Prolog predicate Name is unified with the Prolog variable ErrorList. Cannot be used without foreign/1 or foreign/2.

PREDICATE

Usage: zmq_send_multipart(SocketAtom,Parts,Options)

  • Description: Sends a multipart message over socket SocketAtom using option list Options (the only usable option is currently noblock). Parts is a (ground, proper) list of elements of the form Size:Bytelist or ByteList. In the latter case, the size is calculated using length/2.
  • Call and exit should be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:list/1)Parts is a list.
    (basic_props:list/2)Options is a list of atms.

PREDICATE

Usage: zmq_recv_multipart(SocketAtom,Maybe,Parts,Options)

  • Description: Receives a multipart message over socket SocketAtom using option list Option (the only usable option is currently noblock). Maybe is set either to none (no message parts read) or to some (some message parts read). Parts contains the message parts in the format Size:ByteList
  • Call and exit should be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:atm/1)Maybe is an atom.
    (basic_props:list/1)Parts is a list.
    (basic_props:list/1)Options is a list.

PREDICATE
Sends a list of terms over the given sockets. The terms are serialized before sending.

Usage: zmq_send_terms(SocketAtom,Terms,Options)

  • Description: Send list of terms Terms over socket SocketAtom using options Options. The meaning of Options is the same as in zmq_send_multipart/3.
  • Call and exit should be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:list/1)Terms is a list.
    (basic_props:list/2)Options is a list of atms.

PREDICATE
Receives a list of terms from the given socket sent using zmq_send_terms/3

Usage: zmq_recv_terms(SocketAtom,Maybe,Terms,Options)

  • Description: Receive list of terms Terms over socket SocketAtom. The meaning of Maybe and Options is the same as in zmq_send_multipart/3. Each list item of Terms is constructed using a disjoint set of free variables.
  • Call and exit should be compatible with:
    (basic_props:atm/1)SocketAtom is an atom.
    (basic_props:atm/1)Maybe is an atom.
    (basic_props:list/1)Terms is a list.
    (basic_props:list/1)Options is a list.

PREDICATE

Usage:

  • Description: Starts a responder (resp type) socket that reads messages from TCP port 64321 on the local machine. While waiting for inbound messages, every five seconds prints a reminder on the screen. Replies with “Ok” to each received message. Stops and closes the socket after receiving a message of length zero.

PREDICATE

Usage: demo_requester(ByteList)

  • Description: Same as demo_requester/2, except that it connects specifically to tcp://locahost:64321.

PREDICATE

Usage: demo_requester(Endpoint,ByteList)

  • Description: Sends a message ByteList to a responder socket listening on Endpoint, then waits for the response, prints it and finishes.