Class: ZMQ::Message

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/zmq/message.rb,
ext/rbczmq/message.c

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.ZMQ::Message.decode("\006header\004body") ⇒ ZMQ::Message

Decode a buffer into a new message. Returns nil if the buffer is not properly formatted.

Examples

msg = ZMQ::Message.decode("\006header\004body")
msg.popstr     =>   "header"
msg.popstr     =>   "body"

503
504
505
506
507
508
509
510
# File 'ext/rbczmq/message.c', line 503

static VALUE rb_czmq_message_s_decode(ZMQ_UNUSED VALUE obj, VALUE buffer)
{
    zmsg_t * m = NULL;
    Check_Type(buffer, T_STRING);
    m = zmsg_decode((byte *)StringValueCStr(buffer), RSTRING_LEN(buffer));
    if (m == NULL) return Qnil;
    return rb_czmq_alloc_message(m);
}

Instance Method Details

#==(other) ⇒ Boolean

Determines if a message equals another. True if size, content size and serialized representation is equal.

Examples

msg = ZMQ::Message("header", "body")
other = ZMQ::Message("header", "body")
msg == other    =>   true

560
561
562
563
564
# File 'ext/rbczmq/message.c', line 560

static VALUE rb_czmq_message_equals(VALUE obj, VALUE other_message)
{
    if (obj == other_message) return Qtrue;
    return rb_czmq_message_eql_p(obj, other_message);
}

#add(frame) ⇒ Boolean

Add frame to the end of the message, after all other frames. Message takes ownership of the frame and will destroy it when message is sent.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.add ZMQ::Frame(test)    =>   true
msg.size     =>   1

151
152
153
154
155
156
157
158
159
160
161
# File 'ext/rbczmq/message.c', line 151

static VALUE rb_czmq_message_add(VALUE obj, VALUE frame_obj)
{
    int rc = 0;
    errno = 0;
    ZmqGetMessage(obj);
    ZmqGetFrame(frame_obj);
    rc = zmsg_add(message->message, frame);
    ZmqAssert(rc);
    rb_czmq_frame_freed(frame);
    return Qtrue;
}

#addstr(frame) ⇒ Boolean

Push a string as a new frame to the end of the message, after all other frames.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.addstr "test"    =>   true

338
339
340
341
342
343
344
345
346
347
# File 'ext/rbczmq/message.c', line 338

static VALUE rb_czmq_message_addstr(VALUE obj, VALUE str)
{
    int rc = 0;
    errno = 0;
    ZmqGetMessage(obj);
    Check_Type(str, T_STRING);
    rc = zmsg_addmem(message->message, StringValueCStr(str), RSTRING_LEN(str));
    ZmqAssert(rc);
    return Qtrue;
}

#content_sizeFixnum

Returns the content size of a given ZMQ::Message instance - the sum of each frame's length.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.content_size    =>   0
msg.pushstr "frame"  =>  true
msg.content_size    =>   5

105
106
107
108
109
# File 'ext/rbczmq/message.c', line 105

static VALUE rb_czmq_message_content_size(VALUE obj)
{
    ZmqGetMessage(obj);
    return INT2NUM(zmsg_content_size(message->message));
}

#destroynil

Destroys a ZMQ::Message instance and all the frames it contains. Useful for manual memory management, otherwise the GC will take the same action if a message object is not reachable anymore on the next GC cycle. This is a lower level API.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.destroy    =>   nil

460
461
462
463
464
465
# File 'ext/rbczmq/message.c', line 460

static VALUE rb_czmq_message_destroy(VALUE obj)
{
    ZmqGetMessage(obj);
    rb_czmq_free_message(message);
    return Qnil;
}

#dupZMQ::Message

Creates a copy of this message

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.dup    =>   ZMQ::Message

432
433
434
435
436
437
438
439
440
441
442
443
444
# File 'ext/rbczmq/message.c', line 432

static VALUE rb_czmq_message_dup(VALUE obj)
{
    VALUE dup;
    zmq_message_wrapper *dup_msg = NULL;
    errno = 0;
    ZmqGetMessage(obj);
    dup = Data_Make_Struct(rb_cZmqMessage, zmq_message_wrapper, 0, rb_czmq_free_message_gc, dup_msg);
    dup_msg->message = zmsg_dup(message->message);
    ZmqAssertObjOnAlloc(dup_msg->message, dup_msg);
    dup_msg->flags = message->flags;
    rb_obj_call_init(dup, 0, NULL);
    return dup;
}

#encodeString

Encodes the message to a new buffer.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "body"
msg.pushstr "header"
msg.encode     =>   "\006header\004body"

481
482
483
484
485
486
487
488
# File 'ext/rbczmq/message.c', line 481

static VALUE rb_czmq_message_encode(VALUE obj)
{
    byte *buff;
    size_t buff_size;
    ZmqGetMessage(obj);
    buff_size = zmsg_encode(message->message, &buff);
    return rb_str_new((char *)buff, buff_size);
}

#==(other) ⇒ Boolean

Determines if a message equals another. True if size, content size and serialized representation is equal.

Examples

msg = ZMQ::Message("header", "body")
other = ZMQ::Message("header", "body")
msg == other    =>   true

560
561
562
563
564
# File 'ext/rbczmq/message.c', line 560

static VALUE rb_czmq_message_equals(VALUE obj, VALUE other_message)
{
    if (obj == other_message) return Qtrue;
    return rb_czmq_message_eql_p(obj, other_message);
}

#firstZMQ::Frame?

Resets the cursor to the first message frame, if any.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "test"    =>   true
msg.first    =>   ZMQ::Frame
msg.first    =>   nil

221
222
223
224
225
226
227
228
# File 'ext/rbczmq/message.c', line 221

static VALUE rb_czmq_message_first(VALUE obj)
{
    zframe_t *frame = NULL;
    ZmqGetMessage(obj);
    frame = zmsg_first(message->message);
    if (frame == NULL) return Qnil;
    return rb_czmq_alloc_frame(zframe_dup(frame));
}

#lastZMQ::Frame?

Resets the cursor to the last message frame, if any.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "test"    =>   true
msg.last    =>   ZMQ::Frame
msg.last    =>   nil

268
269
270
271
272
273
274
275
# File 'ext/rbczmq/message.c', line 268

static VALUE rb_czmq_message_last(VALUE obj)
{
    zframe_t *frame = NULL;
    ZmqGetMessage(obj);
    frame = zmsg_last(message->message);
    if (frame == NULL) return Qnil;
    return rb_czmq_alloc_frame(zframe_dup(frame));
}

#nextZMQ::Frame?

Returns the next message frame or nil if there aren't anymore. Advances the frames cursor and can thus be used for iteration.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "test"    =>   true
msg.next    =>   ZMQ::Frame
msg.next    =>   nil

245
246
247
248
249
250
251
252
# File 'ext/rbczmq/message.c', line 245

static VALUE rb_czmq_message_next(VALUE obj)
{
    zframe_t *frame = NULL;
    ZmqGetMessage(obj);
    frame = zmsg_next(message->message);
    if (frame == NULL) return Qnil;
    return rb_czmq_alloc_frame(zframe_dup(frame));
}

#popZMQ::Frame?

Remove first frame from message, if any. Returns a ZMQ::Frame instance or nil. Caller now owns the frame.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "test"    =>   true
msg.pop    =>   ZMQ::Frame
msg.size    =>   1
msg.pop    =>   nil

178
179
180
181
182
183
184
185
# File 'ext/rbczmq/message.c', line 178

static VALUE rb_czmq_message_pop(VALUE obj)
{
    zframe_t *frame = NULL;
    ZmqGetMessage(obj);
    frame = zmsg_pop(message->message);
    if (frame == NULL) return Qnil;
    return rb_czmq_alloc_frame(frame);
}

#popstrString?

Pop frame off front of message, return as a new string.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.addstr "test"    =>   true
msg.popstr    =>   "test"

362
363
364
365
366
367
368
369
# File 'ext/rbczmq/message.c', line 362

static VALUE rb_czmq_message_popstr(VALUE obj)
{
    char *str = NULL;
    ZmqGetMessage(obj);
    str = zmsg_popstr(message->message);
    if (str == NULL) return Qnil;
    return rb_str_new2(str);
}

Dumps the first 10 frames of the message to stderr for debugging.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "test"    =>   true
msg.print    =>   nil

200
201
202
203
204
205
# File 'ext/rbczmq/message.c', line 200

static VALUE rb_czmq_message_print(VALUE obj)
{
    ZmqGetMessage(obj);
    zmsg_dump(message->message);
    return Qnil;
}

#push(frame) ⇒ Boolean

Push frame to the front of the message, before all other frames. Message takes ownership of the frame and will destroy it when message is sent.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.push ZMQ::Frame(test)    =>   true
msg.size     =>   1

125
126
127
128
129
130
131
132
133
134
135
# File 'ext/rbczmq/message.c', line 125

static VALUE rb_czmq_message_push(VALUE obj, VALUE frame_obj)
{
    int rc = 0;
    errno = 0;
    ZmqGetMessage(obj);
    ZmqGetFrame(frame_obj);
    rc = zmsg_push(message->message, frame);
    ZmqAssert(rc);
    rb_czmq_frame_freed(frame);
    return Qtrue;
}

#pushstr(frame) ⇒ Boolean

Push a string as a new frame to the front of the message, before all other frames.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.pushstr "test"    =>   true

315
316
317
318
319
320
321
322
323
324
# File 'ext/rbczmq/message.c', line 315

static VALUE rb_czmq_message_pushstr(VALUE obj, VALUE str)
{
    int rc = 0;
    errno = 0;
    ZmqGetMessage(obj);
    Check_Type(str, T_STRING);
    rc = zmsg_pushmem(message->message, StringValueCStr(str), RSTRING_LEN(str));
    ZmqAssert(rc);
    return Qtrue;
}

#remove(frame) ⇒ nil

Removes the given frame from the message's frame list if present. Does not destroy the frame itself.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
frame = ZMQ::Frame("test")    =>  ZMQ::Frame
msg.push(frame)    =>   true
msg.size     =>   1
msg.remove(frame)    =>   nil
msg.size     =>   0

293
294
295
296
297
298
299
300
301
# File 'ext/rbczmq/message.c', line 293

static VALUE rb_czmq_message_remove(VALUE obj, VALUE frame_obj)
{
    ZmqGetMessage(obj);
    zframe_t *frame = NULL;
    ZmqAssertFrame(frame_obj);
    Data_Get_Struct(frame_obj, zframe_t, frame);
    zmsg_remove(message->message, frame);
    return Qnil;
}

#sizeFixnum

Returns the size of a given ZMQ::Message instance - the number of frames.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.size    =>   0
msg.pushstr "frame"  =>  true
msg.size    =>   1

85
86
87
88
89
# File 'ext/rbczmq/message.c', line 85

static VALUE rb_czmq_message_size(VALUE obj)
{
    ZmqGetMessage(obj);
    return INT2NUM(zmsg_size(message->message));
}

#to_aArray

Returns an Array of all frames this message is composed of.

Examples

ZMQ::Message.new.to_a                 =>   []
msg = ZMQ::Message("header", "body")  =>   ZMQ::Message
msg.to_a                              =>   [ZMQ::Frame("header"), ZMQ::Frame("body")]

579
580
581
582
583
584
585
586
587
588
589
590
# File 'ext/rbczmq/message.c', line 579

static VALUE rb_czmq_message_to_a(VALUE obj)
{
    VALUE ary;
    ZmqGetMessage(obj);
    ary = rb_ary_new2(zmsg_size(message->message));
    zframe_t *frame = zmsg_first(message->message);
    while (frame) {
        rb_ary_push(ary, rb_czmq_alloc_frame(zframe_dup(frame)));
        frame = zmsg_next(message->message);
    }
    return ary;
}

#unwrapZMQ::Frame?

Pop frame off front of message, caller now owns frame. If next frame is empty, pops and destroys that empty frame.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
frame = ZMQ::Frame("test")     =>   ZMQ::Frame
msg.wrap ZMQ::Frame("test")    =>   nil
msg.size     =>   2
msg.unwrap     =>   frame
msg.size     =>   0

411
412
413
414
415
416
417
418
# File 'ext/rbczmq/message.c', line 411

static VALUE rb_czmq_message_unwrap(VALUE obj)
{
    zframe_t *frame = NULL;
    ZmqGetMessage(obj);
    frame = zmsg_unwrap(message->message);
    if (frame == NULL) return Qnil;
    return rb_czmq_alloc_frame(frame);
}

#wrap(frame) ⇒ nil

Push frame plus empty frame to front of message, before the first frame. Message takes ownership of frame, will destroy it when message is sent.

Examples

msg = ZMQ::Message.new    =>  ZMQ::Message
msg.wrap ZMQ::Frame("test")    =>   nil
msg.size     =>   2

385
386
387
388
389
390
391
392
393
# File 'ext/rbczmq/message.c', line 385

static VALUE rb_czmq_message_wrap(VALUE obj, VALUE frame_obj)
{
    errno = 0;
    ZmqGetMessage(obj);
    ZmqGetFrame(frame_obj);
    zmsg_wrap(message->message, frame);
    rb_czmq_frame_freed(frame);
    return Qnil;
}