def send(m, socket):
"""
Send message to socket, destroy after sending. If the message has no
frames, sends nothing but destroys the message anyhow. Safe to call
if zmsg is null.
"""
C.zmsg_send(ptop('zmsg_t', m), socket)
def apply(cert, zocket):
"""
Apply certificate to socket, i.e. use for CURVE security on socket.
If certificate was loaded from public file, the secret key will be
undefined, and this certificate will not work successfully.
"""
C.zcert_apply(cert, zocket)
def destroy(loop):
"""
Destroy a reactor, this is not necessary if you create it with
new.
"""
if loop is not ffi.NULL:
C.zloop_destroy(ptop('zloop_t', loop))
return ffi.NULL
def destroy(loop):
"""
Destroy a reactor, this is not necessary if you create it with
new.
"""
if loop is not ffi.NULL:
C.zloop_destroy(ptop('zloop_t', loop))
return ffi.NULL
def append(m, f):
"""
Add frame to the end of the message, i.e. after all other frames.
Message takes ownership of frame, will destroy it when message is sent.
Returns 0 on success. Deprecates zmsg_add, which did not nullify the
caller's frame reference.
"""
C.zmsg_append(m, ptop('zframe_t', f))
def destroy(ctx, socket):
"""Destroy a socket within our CZMQ context.
'pyczmq.zsocket.new' automatically registers this destructor with
the garbage collector, so this is normally not necessary to use,
unless you need to destroy sockets created by some other means
(like a call directly to 'pyczmq.C.zsocket_new')
"""
C.zsocket_destroy(ctx, socket)
def zsys_version():
"""
Returns the tuple (major, minor, patch) of the current czmq version.
"""
major = ffi.new('int*')
minor= ffi.new('int*')
patch = ffi.new('int*')
C.zsys_version(major, minor, patch)
return (major[0], minor[0], patch[0])
def destroy(ctx, socket):
"""Destroy a socket within our CZMQ context.
'pyczmq.zsocket.new' automatically registers this destructor with
the garbage collector, so this is normally not necessary to use,
unless you need to destroy sockets created by some other means
(like a call directly to 'pyczmq.C.zsocket_new')
"""
C.zsocket_destroy(ctx, socket)
def poller_end(loop, item):
"""
Cancel a pollitem from the reactor, specified by socket or FD. If both
are specified, uses only socket. If multiple poll items exist for same
socket/FD, cancels ALL of them.
"""
return C.zloop_poller_end(loop, item)
def recv(sock):
"""
Receive frame from socket, returns zframe_t object or NULL if the recv
was interrupted. Does a blocking recv, if you want to not block then use
zframe_recv_nowait().
"""
return C.zframe_recv(sock)
def sendx(sock, *strings):
"""
Send a series of strings (until NULL) as multipart data
Returns 0 if the strings could be sent OK, or -1 on error.
"""
varargs = [ffi.new('char[]', s) for s in strings] + [ffi.NULL]
return C.zstr_sendx(sock, *varargs)
def new(type, filename=None, line_nbr=None):
if filename is None:
frame = inspect.stack()[1][0]
info = inspect.getframeinfo(frame)
filename = info.filename
line_nbr = info.lineno
return ffi.gc(C.zsock_new(type, filename, line_nbr), destroy)
def sendx(sock, *strings):
"""
Send a series of strings (until NULL) as multipart data
Returns 0 if the strings could be sent OK, or -1 on error.
"""
varargs = [ffi.new('char[]', s) for s in strings] + [ffi.NULL]
return C.zstr_sendx(sock, *varargs)
def new_empty():
"""Create an empty (zero-sized) frame.
Note, no gc wrapper, frames self-destruct by send. If you don't
send a frame, you DO have to destroy() it.
"""
return C.zframe_new_empty()
def new(data):
"""Create a new frame with optional size, and optional data
Note, no gc wrapper, frames self-destruct by send. If you don't
send a frame, you DO have to destroy() it.
"""
return C.zframe_new(data, len(data))
def set_rcvhwm(ctx, rcvhwm):
"""
Set initial receive HWM for all new normal sockets created in context.
You can set this per-socket after the socket is created.
The default, no matter the underlying ZeroMQ version, is 1,000.
"""
return C.zctx_set_rcvhwm(ctx, rcvhwm)
def load(msg, filename):
"""
Load/append an open file into message, create new message if
null message provided. Returns NULL if the message could not
be loaded.
"""
return C.zmsg_load(msg, filename)
def new():
"""Create a new empty message object,
Note, no gc wrapper, messages self-destruct by send. If you don't
send a message, you DO have to destroy() it.
"""
return C.zmsg_new()
def recv(sock):
"""
Receive frame from socket, returns zframe_t object or NULL if the recv
was interrupted. Does a blocking recv, if you want to not block then use
zframe_recv_nowait().
"""
return C.zframe_recv(sock)
def insert(store, cert):
"""
Insert certificate into certificate store in memory. Note that this
does not save the certificate to disk. To do that, use zcert_save()
directly on the certificate. Takes ownership of zcert_t object.
"""
return C.zcertstore_insert(store, ptop('zcert_t', cert))
def new_empty():
"""Create an empty (zero-sized) frame.
Note, no gc wrapper, frames self-destruct by send. If you don't
send a frame, you DO have to destroy() it.
"""
return C.zframe_new_empty()
def poller_end(loop, item):
"""
Cancel a pollitem from the reactor, specified by socket or FD. If both
are specified, uses only socket. If multiple poll items exist for same
socket/FD, cancels ALL of them.
"""
return C.zloop_poller_end(loop, item)
def signal(sock, status):
"""Send a signal over a socket. A signal is a short message carrying a
success/failure code (by convention, 0 means OK). Signals are encoded
to be distinguishable from "normal" messages. Accepts a zock_t or a
zactor_t argument, and returns 0 if successful, -1 if the signal could
not be sent."""
return C.zsock_signal(sock, status)
def recv(socket):
"""
Receive message from socket, returns zmsg_t object or NULL if the recv
was interrupted. Does a blocking recv, if you want to not block then use
the zloop class or zmq_poll to check for socket input before receiving.
"""
return C.zmsg_recv(socket)
def send(m, socket):
"""
Send message to socket, destroy after sending. If the message has no
frames, sends nothing but destroys the message anyhow. Safe to call
if zmsg is null.
"""
return C.zmsg_send(ptop('zmsg_t', m), socket)
def load(msg, filename):
"""
Load/append an open file into message, create new message if
null message provided. Returns NULL if the message could not
be loaded.
"""
return C.zmsg_load(msg, filename)
def new():
"""Create a new empty message object,
Note, no gc wrapper, messages self-destruct by send. If you don't
send a message, you DO have to destroy() it.
"""
return C.zmsg_new()
def insert(store, cert):
"""
Insert certificate into certificate store in memory. Note that this
does not save the certificate to disk. To do that, use zcert_save()
directly on the certificate. Takes ownership of zcert_t object.
"""
return C.zcertstore_insert(store, ptop('zcert_t', cert))
def push(msg, frame):
"""
Push frame to the front of the message, i.e. before all other frames.
Message takes ownership of frame, will destroy it when message is sent.
Returns 0 on success, -1 on error.
"""
return C.zmsg_push(msg, frame)
def recv(socket):
"""
Receive message from socket, returns zmsg_t object or NULL if the recv
was interrupted. Does a blocking recv, if you want to not block then use
the zloop class or zmq_poll to check for socket input before receiving.
"""
return C.zmsg_recv(socket)
def new(data):
"""Create a new frame with optional size, and optional data
Note, no gc wrapper, frames self-destruct by send. If you don't
send a frame, you DO have to destroy() it.
"""
return C.zframe_new(data, len(data))
def set_rcvhwm(ctx, rcvhwm):
"""
Set initial receive HWM for all new normal sockets created in context.
You can set this per-socket after the socket is created.
The default, no matter the underlying ZeroMQ version, is 1,000.
"""
return C.zctx_set_rcvhwm(ctx, rcvhwm)
def push(msg, frame):
"""
Push frame to the front of the message, i.e. before all other frames.
Message takes ownership of frame, will destroy it when message is sent.
Returns 0 on success, -1 on error.
"""
return C.zmsg_push(msg, frame)
def set_iothreads(ctx, iothreads):
"""
Raise default I/O threads from 1, for crazy heavy applications
The rule of thumb is one I/O thread per gigabyte of traffic in
or out. Call this method before creating any sockets on the context
or the setting will have no effect.
"""
return C.zctx_set_iothreads(ctx, iothreads)
def timer(loop, delay, times, handler, arg):
"""
Register a timer that expires after some delay and repeats some number of
times. At each expiry, will call the handler, passing the arg. To
run a timer forever, use 0 times. Returns 0 if OK, -1 if there was an
error.
"""
return C.zloop_timer(loop, delay, times, handler, arg)
def start(loop):
"""
Start the reactor. Takes control of the thread and returns when the 0MQ
context is terminated or the process is interrupted, or any event handler
returns -1. Event handlers may register new sockets and timers, and
cancel sockets. Returns 0 if interrupted, -1 if cancelled by a handler.
"""
return C.zloop_start(loop)
def set_linger(ctx, linger):
"""
Set msecs to flush sockets when closing them, see the ZMQ_LINGER
man page section for more details. By default, set to zero, so
any in-transit messages are discarded when you destroy a socket or
a context.
"""
return C.zctx_set_linger(ctx, linger)
def start(loop):
"""
Start the reactor. Takes control of the thread and returns when the 0MQ
context is terminated or the process is interrupted, or any event handler
returns -1. Event handlers may register new sockets and timers, and
cancel sockets. Returns 0 if interrupted, -1 if cancelled by a handler.
"""
return C.zloop_start(loop)
def append(m, f):
"""
Add frame to the end of the message, i.e. after all other frames.
Message takes ownership of frame, will destroy it when message is sent.
Returns 0 on success. Deprecates zmsg_add, which did not nullify the
caller's frame reference.
"""
return C.zmsg_append(m, ptop('zframe_t', f))
def new(ctx, typ):
"""
Create a new socket within our CZMQ context, replaces zmq_socket.
Use this to get automatic management of the socket at shutdown.
Note: SUB sockets do not automatically subscribe to everything;
you must set filters explicitly.
"""
return ffi.gc(C.zsocket_new(ctx, typ), lambda s: destroy(ctx, s))
def wait(poller, timeout):
"""
Poll the registered readers for I/O, return first socket that has input.
This means the order that sockets are defined in the poll list affects
their priority. If you need a balanced poll, use the low level zmq_poll
method directly.
"""
return C.zpoller_wait(poller, timeout)
def timer(loop, delay, times, handler, arg):
"""
Register a timer that expires after some delay and repeats some number of
times. At each expiry, will call the handler, passing the arg. To
run a timer forever, use 0 times. Returns a timer_id or -1 if there was an
error.
"""
return C.zloop_timer(loop, delay, times, handler, ffi.new_handle(arg))
def save(cert, filename):
"""
Save full certificate (public + secret) to file for persistent
storage This creates one public file and one secret file (filename
+ "_secret"). The filename is treated as a printf format
specifier.
"""
return C.zcert_save(cert, filename)
def wait(poller, timeout):
"""
Poll the registered readers for I/O, return first socket that has input.
This means the order that sockets are defined in the poll list affects
their priority. If you need a balanced poll, use the low level zmq_poll
method directly.
"""
return C.zpoller_wait(poller, timeout)
def set_linger(ctx, linger):
"""
Set msecs to flush sockets when closing them, see the ZMQ_LINGER
man page section for more details. By default, set to zero, so
any in-transit messages are discarded when you destroy a socket or
a context.
"""
return C.zctx_set_linger(ctx, linger)
def bind(sock, endpoint):
""" Bind a socket to a formatted endpoint. If the port is specified as '*'
and the endpoint starts with "tcp://", binds to an ephemeral TCP port in
a high range. Always returns the port number on successful TCP binds, else
returns zero on success. Returns -1 on failure. When using ephemeral ports,
note that ports may be reused by different threads, without clients being
aware."""
return C.zsock_bind(sock, endpoint)
def new(ctx, typ):
"""
Create a new socket within our CZMQ context, replaces zmq_socket.
Use this to get automatic management of the socket at shutdown.
Note: SUB sockets do not automatically subscribe to everything;
you must set filters explicitly.
"""
return ffi.gc(C.zsocket_new(ctx, typ), lambda s: destroy(ctx, s))
def set_iothreads(ctx, iothreads):
"""
Raise default I/O threads from 1, for crazy heavy applications
The rule of thumb is one I/O thread per gigabyte of traffic in
or out. Call this method before creating any sockets on the context
or the setting will have no effect.
"""
return C.zctx_set_iothreads(ctx, iothreads)
def recvx(sock, string_p):
"""
Receive a series of strings (until NULL) from multipart data
Each string is allocated and filled with string data; if there
are not enough frames, unallocated strings are set to NULL.
Returns -1 if the message could not be read, else returns the
number of strings filled, zero or more.
"""
return C.zstr_recvx(sock, string_p)
def configure_plain(auth, domain, filename):
"""
Configure PLAIN authentication for a given domain. PLAIN
authentication uses a plain-text password file. The filename is
treated as a printf format. To cover all domains, use "*". You can
modify the password file at any time; it is reloaded
automatically.
"""
return C.zauth_configure_plain(auth, domain, filename)
def deny(auth, addr):
"""
Deny (blacklist) a single IP address. For all security mechanisms,
this rejects the connection without any further
authentication. Use either a whitelist, or a blacklist, not not
both. If you define both a whitelist and a blacklist, only the
whitelist takes effect.
"""
return C.zauth_deny(auth, addr)
def poller(p, item, handler, arg=None):
"""
Register pollitem with the reactor. When the pollitem is ready, will call
the handler, passing the arg. Returns 0 if OK, -1 if there was an error.
If you register the pollitem more than once, each instance will invoke its
corresponding handler.
"""
return C.zloop_poller(p, item, handler, ffi.new_handle(arg))
def bind(sock, fmt):
"""
Bind a socket to a formatted endpoint. If the port is specified as
'*', binds to any free port from ZSOCKET_DYNFROM to ZSOCKET_DYNTO
and returns the actual port number used. Otherwise asserts that
the bind succeeded with the specified port number. Always returns
the port number if successful.
"""
return C.zsocket_bind(sock, fmt)
def deny(auth, addr):
"""
Deny (blacklist) a single IP address. For all security mechanisms,
this rejects the connection without any further
authentication. Use either a whitelist, or a blacklist, not not
both. If you define both a whitelist and a blacklist, only the
whitelist takes effect.
"""
return C.zauth_deny(auth, addr)
def configure_plain(auth, domain, filename):
"""
Configure PLAIN authentication for a given domain. PLAIN
authentication uses a plain-text password file. The filename is
treated as a printf format. To cover all domains, use "*". You can
modify the password file at any time; it is reloaded
automatically.
"""
return C.zauth_configure_plain(auth, domain, filename)
def save(msg, filename):
"""
Save message to an open file, return 0 if OK, else -1. The message is
saved as a series of frames, each with length and data. Note that the
file is NOT guaranteed to be portable between operating systems, not
versions of CZMQ. The file format is at present undocumented and liable
to arbitrary change.
"""
return C.zmsg_save(msg, filename)
def save(msg, filename):
"""
Save message to an open file, return 0 if OK, else -1. The message is
saved as a series of frames, each with length and data. Note that the
file is NOT guaranteed to be portable between operating systems, not
versions of CZMQ. The file format is at present undocumented and liable
to arbitrary change.
"""
return C.zmsg_save(msg, filename)
