zctx(3)

zctx(3)

CZMQ Manual - CZMQ/2.2.1

Name

zctx - working with ØMQ contexts

Synopsis

//  Create new context, returns context object, replaces zmq_init
CZMQ_EXPORT zctx_t *
    zctx_new (void);

//  Destroy context and all sockets in it, replaces zmq_term
CZMQ_EXPORT void
    zctx_destroy (zctx_t **self_p);

//  Create new shadow context, returns context object
CZMQ_EXPORT zctx_t *
    zctx_shadow (zctx_t *self);
//  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 calling zctx_shadow, or the setting will have no effect.
CZMQ_EXPORT void
    zctx_set_iothreads (zctx_t *self, int iothreads);

//  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.
CZMQ_EXPORT void
    zctx_set_linger (zctx_t *self, int linger);

//  Set initial high-water mark for inter-thread pipe sockets. Note that
//  this setting is separate from the default for normal sockets. You
//  should change the default for pipe sockets *with care*. Too low values
//  will cause blocked threads, and an infinite setting can cause memory
//  exhaustion. The default, no matter the underlying ZeroMQ version, is
//  1,000.
CZMQ_EXPORT void
    zctx_set_pipehwm (zctx_t *self, int pipehwm);

//  Set initial send 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.
CZMQ_EXPORT void
    zctx_set_sndhwm (zctx_t *self, int sndhwm);

//  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.
CZMQ_EXPORT void
    zctx_set_rcvhwm (zctx_t *self, int rcvhwm);

//  Return low-level ØMQ context object, will be NULL before first socket
//  is created. Use with care.
CZMQ_EXPORT void *
    zctx_underlying (zctx_t *self);

//  Self test of this class
CZMQ_EXPORT int
    zctx_test (bool verbose);

//  Global signal indicator, TRUE when user presses Ctrl-C or the process
//  gets a SIGTERM signal.
CZMQ_EXPORT extern volatile int zctx_interrupted;

Description

The zctx class wraps ØMQ contexts. It manages open sockets in the context and automatically closes these before terminating the context. It provides a simple way to set the linger timeout on sockets, and configure contexts for number of I/O threads. Sets-up signal (interrupt) handling for the process.

The zctx class has these main features:

  • Tracks all open sockets and automatically closes them before calling zmq_term(). This avoids an infinite wait on open sockets.
  • Automatically configures sockets with a ZMQ_LINGER timeout you can define, and which defaults to zero. The default behavior of zctx is therefore like ØMQ/2.0, immediate termination with loss of any pending messages. You can set any linger timeout you like by calling the zctx_set_linger() method.
  • Moves the iothreads configuration to a separate method, so that default usage is 1 I/O thread. Lets you configure this value.
  • Sets up signal (SIGINT and SIGTERM) handling so that blocking calls such as zmq_recv() and zmq_poll() will return when the user presses Ctrl-C.

Example

From zctx_test method

 // Create and destroy a context without using it
 zctx_t *ctx = zctx_new ();
 assert (ctx);
 zctx_destroy (&ctx);
 assert (ctx == NULL);

 // Create a context with many busy sockets, destroy it
 ctx = zctx_new ();
 assert (ctx);
 zctx_set_iothreads (ctx, 1);
 zctx_set_linger (ctx, 5); // 5 msecs
 void *s1 = zctx__socket_new (ctx, ZMQ_PAIR);
 void *s2 = zctx__socket_new (ctx, ZMQ_XREQ);
 void *s3 = zctx__socket_new (ctx, ZMQ_REQ);
 void *s4 = zctx__socket_new (ctx, ZMQ_REP);
 void *s5 = zctx__socket_new (ctx, ZMQ_PUB);
 void *s6 = zctx__socket_new (ctx, ZMQ_SUB);
 zsocket_connect (s1, "tcp://127.0.0.1:5555");
 zsocket_connect (s2, "tcp://127.0.0.1:5555");
 zsocket_connect (s3, "tcp://127.0.0.1:5555");
 zsocket_connect (s4, "tcp://127.0.0.1:5555");
 zsocket_connect (s5, "tcp://127.0.0.1:5555");
 zsocket_connect (s6, "tcp://127.0.0.1:5555");
 assert (zctx_underlying (ctx));  zctx_destroy (&ctx);

See also

czmq(7)

Authors

The CZMQ manual was written by Pieter Hintjens<moc.xitami|hp#moc.xitami|hp>.

Resources

Main web site: http://czmq.zeromq.org/

Report bugs to the ØMQ development mailing list: <gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez>

Copyright

Copyright (c) 1991-2014 iMatix and Contributors. License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>. This is free software: you are free to change it and redistribute it. There is NO WARRANTY, to the extent permitted by law. For details see the files COPYING and COPYING.LESSER included with the CZMQ distribution.