zframe(3)

zframe(3)

CZMQ Manual - CZMQ/1.4.1

Name

zframe - working with single message frames

Synopsis

#define ZFRAME_MORE     1
#define ZFRAME_REUSE    2
#define ZFRAME_DONTWAIT 4

//  Callback function for zframe_free_fn method
typedef void (zframe_free_fn) (void *data, void *arg);

//  Create a new frame with optional size, and optional data
CZMQ_EXPORT zframe_t *
    zframe_new (const void *data, size_t size);

//  Create a zero-copy frame
CZMQ_EXPORT zframe_t *
    zframe_new_zero_copy (void *data, size_t size,
                          zframe_free_fn *free_fn, void *arg);

//  Destroy a frame
CZMQ_EXPORT void
    zframe_destroy (zframe_t **self_p);

//  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().
CZMQ_EXPORT zframe_t *
    zframe_recv (void *socket);

//  Receive a new frame off the socket. Returns newly allocated frame, or
//  NULL if there was no input waiting, or if the read was interrupted.
CZMQ_EXPORT zframe_t *
    zframe_recv_nowait (void *socket);

// Send a frame to a socket, destroy frame after sending.  Returns
// non-zero error code on failure.
CZMQ_EXPORT int
    zframe_send (zframe_t **self_p, void *socket, int flags);

//  Return number of bytes in frame data
CZMQ_EXPORT size_t
    zframe_size (zframe_t *self);

//  Return address of frame data
CZMQ_EXPORT byte *
    zframe_data (zframe_t *self);

//  Create a new frame that duplicates an existing frame
CZMQ_EXPORT zframe_t *
    zframe_dup (zframe_t *self);

//  Return frame data encoded as printable hex string
CZMQ_EXPORT char *
    zframe_strhex (zframe_t *self);

//  Return frame data copied into freshly allocated string
CZMQ_EXPORT char *
    zframe_strdup (zframe_t *self);

//  Return TRUE if frame body is equal to string, excluding terminator
CZMQ_EXPORT bool
    zframe_streq (zframe_t *self, const char *string);

// Return frame zero copy indicator (1 or 0)
CZMQ_EXPORT int
    zframe_zero_copy (zframe_t *self);

//  Return frame 'more' property
CZMQ_EXPORT int
    zframe_more (const zframe_t *self);

//  Return TRUE if two frames have identical size and data
//  If either frame is NULL, equality is always false.
CZMQ_EXPORT bool
    zframe_eq (zframe_t *self, zframe_t *other);

//  Print contents of frame to stderr
CZMQ_EXPORT void
    zframe_print (zframe_t *self, const char *prefix);

//  Set new contents for frame
CZMQ_EXPORT void
    zframe_reset (zframe_t *self, const void *data, size_t size);

//  Set the free callback for frame
CZMQ_EXPORT void
    zframe_freefn(zframe_t *self, zframe_free_fn *free_fn, void *arg);

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

Description

The zframe class provides methods to send and receive single message frames across ØMQ sockets. A frame corresponds to one zmq_msg_t. When you read a frame from a socket, the zframe_more() method indicates if the frame is part of an unfinished multipart message. The zframe_send method normally destroys the frame, but with the ZFRAME_REUSE flag, you can send the same frame many times. Frames are binary, and this class has no special support for text data.

Example

From zframe_test method

 zctx_t *ctx = zctx_new ();
 assert (ctx);

 void *output = zsocket_new (ctx, ZMQ_PAIR);
 assert (output);
 zsocket_bind (output, "inproc://zframe.test");
 void *input = zsocket_new (ctx, ZMQ_PAIR);
 assert (input);
 zsocket_connect (input, "inproc://zframe.test");

 // Send five different frames, test ZFRAME_MORE
 int frame_nbr;
 for (frame_nbr = 0; frame_nbr < 5; frame_nbr++) {
 zframe_t *frame = zframe_new ("Hello", 5);
 rc = zframe_send (&frame, output, ZFRAME_MORE);
 assert (rc == 0);
 }
 // Send same frame five times, test ZFRAME_REUSE
 zframe_t *frame = zframe_new ("Hello", 5);
 assert (frame);
 for (frame_nbr = 0; frame_nbr < 5; frame_nbr++) {
 rc = zframe_send (&frame, output, ZFRAME_MORE + ZFRAME_REUSE);
 assert (rc == 0);
 }
 assert (frame);
 zframe_t *copy = zframe_dup (frame);
 assert (zframe_eq (frame, copy));
 zframe_destroy (&frame);
 assert (!zframe_eq (frame, copy));
 assert (zframe_size (copy) == 5);
 zframe_destroy (&copy);
 assert (!zframe_eq (frame, copy));

 // Send END frame
 frame = zframe_new ("NOT", 3);
 assert (frame);
 zframe_reset (frame, "END", 3);
 char *string = zframe_strhex (frame);
 assert (streq (string, "454E44"));
 free (string);
 string = zframe_strdup (frame);
 assert (streq (string, "END"));
 free (string);
 rc = zframe_send (&frame, output, 0);
 assert (rc == 0);

 // Read and count until we receive END
 frame_nbr = 0;
 for (frame_nbr = 0;; frame_nbr++) {
 zframe_t *frame = zframe_recv (input);
 if (zframe_streq (frame, "END")) {
 zframe_destroy (&frame);
 break;
 }
 assert (zframe_more (frame));
 zframe_destroy (&frame);
 }
 assert (frame_nbr == 10);
 frame = zframe_recv_nowait (input);
 assert (frame == NULL);

 // Test zero copy
 char *buffer = (char *) malloc (1024);
 int i;
 for (i = 0; i < 1024; i++)
 buffer [i] = 'A';

 frame = zframe_new_zero_copy (buffer, 1024, s_test_free_cb, NULL);
 zframe_t *frame_copy = zframe_dup (frame);

 assert (zframe_zero_copy (frame) == 1);
 assert (zframe_zero_copy (frame_copy) == 0);

 zframe_destroy (&frame);
 zframe_destroy (&frame_copy);

 frame = zframe_new ("callback", 8);
 zframe_freefn (frame, s_test_free_frame_cb, NULL);
 zframe_destroy (&frame);
  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-2010 iMatix Corporation 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.