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"

Returns:



624
625
626
627
628
629
630
631
 
# File 'ext/rbczmq/message.c', line 624

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 *)RSTRING_PTR(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

Returns:

  • (Boolean) 


683
684
685
686
687
 
# File 'ext/rbczmq/message.c', line 683

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

Returns:

  • (Boolean) 


192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'ext/rbczmq/message.c', line 192

static VALUE rb_czmq_message_add(VALUE obj, VALUE frame_obj)
{
    int rc = 0;
    errno = 0;
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);
    ZmqGetFrame(frame_obj);
    ZmqAssertFrameOwnedNoMessage(frame);

    rc = zmsg_add(message->message, frame->frame);
    ZmqAssert(rc);
    frame->message = message;
    frame->flags &= ~ZMQ_FRAME_OWNED;
    zlist_append(message->frames, (void*)frame_obj);
    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

Returns:

  • (Boolean) 


406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'ext/rbczmq/message.c', line 406

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

    /* keep zlist of frame ruby objects in sync with message's frame list */
    zframe_t* zframe = zmsg_last(message->message);
    VALUE frame_object = rb_czmq_alloc_frame(zframe);
    ZmqGetFrame(frame_object);
    frame->flags &= ~ZMQ_FRAME_OWNED;
    frame->message = message;
    zlist_append(message->frames, (void*)frame_object);

    return Qtrue;
}

#content_size ⇒ Fixnum

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

Returns:

  • (Fixnum) 


140
141
142
143
144
145
 
# File 'ext/rbczmq/message.c', line 140

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

#destroy ⇒ nil

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

Returns:

  • (nil) 


577
578
579
580
581
582
583
 
# File 'ext/rbczmq/message.c', line 577

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

#dup ⇒ ZMQ::Message

Creates a copy of this message

Examples

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

Returns:



554
555
556
557
558
559
560
561
 
# File 'ext/rbczmq/message.c', line 554

static VALUE rb_czmq_message_dup(VALUE obj)
{
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);

    zmsg_t* dup_msg = zmsg_dup(message->message);
    return rb_czmq_alloc_message(dup_msg);
}

#encode ⇒ String

Encodes the message to a new buffer.

Examples

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

Returns:

  • (String) 


599
600
601
602
603
604
605
606
607
608
609
 
# File 'ext/rbczmq/message.c', line 599

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

#==(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

Returns:

  • (Boolean) 


683
684
685
686
687
 
# File 'ext/rbczmq/message.c', line 683

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);
}

#first ⇒ ZMQ::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

Returns:



274
275
276
277
278
279
280
 
# File 'ext/rbczmq/message.c', line 274

static VALUE rb_czmq_message_first(VALUE obj)
{
    ZmqGetMessage(obj);
    ZmqReturnNilUnlessOwned(message);
    VALUE frame_obj = (VALUE)zlist_first(message->frames);
    return frame_obj ? frame_obj : Qnil;
}

#gone?(# = > false) ⇒ Boolean

msg.gone? #=> true

Return boolean indicating if the ZMQ::Message is gone (sent or destroyed). If the message is gone, accessor methods will return nil and methods requiring data or methods that mutate the message will raise an exception.

Returns:

  • (Boolean) 


727
728
729
730
731
 
# File 'ext/rbczmq/message.c', line 727

static VALUE rb_czmq_message_gone(VALUE obj)
{
    ZmqGetMessage(obj);
    return (message->flags & ZMQ_MESSAGE_OWNED) ? Qfalse : Qtrue;
}

#last ⇒ ZMQ::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

Returns:



319
320
321
322
323
324
325
 
# File 'ext/rbczmq/message.c', line 319

static VALUE rb_czmq_message_last(VALUE obj)
{
    ZmqGetMessage(obj);
    ZmqReturnNilUnlessOwned(message);
    VALUE frame_obj = (VALUE)zlist_last(message->frames);
    return frame_obj ? frame_obj : Qnil;
}

#next ⇒ ZMQ::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

Returns:



297
298
299
300
301
302
303
 
# File 'ext/rbczmq/message.c', line 297

static VALUE rb_czmq_message_next(VALUE obj)
{
    ZmqGetMessage(obj);
    ZmqReturnNilUnlessOwned(message);
    VALUE frame_obj = (VALUE)zlist_next(message->frames);
    return frame_obj ? frame_obj : Qnil;
}

#pop ⇒ ZMQ::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

Returns:



224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'ext/rbczmq/message.c', line 224

static VALUE rb_czmq_message_pop(VALUE obj)
{
    zframe_t *zframe = NULL;
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);
    zframe = zmsg_pop(message->message); /* we now own the frame */
    if (zframe == NULL) return Qnil;
    VALUE frame_obj = (VALUE)zlist_pop(message->frames);
    /* detach frame from message, it is now owned by the ruby object */
    ZmqGetFrame(frame_obj);
    frame->flags |= ZMQ_FRAME_OWNED;
    frame->message = NULL;
    return frame_obj ? frame_obj : Qnil;
}

#popstr ⇒ String?

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"

Returns:

  • (String, nil) 


440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'ext/rbczmq/message.c', line 440

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

    /* destroys the frame, keep frame objects list in sync: */
    zlist_pop(message->frames);

    return rb_str_new2(str);
}

#print ⇒ nil

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

Returns:

  • (nil) 


252
253
254
255
256
257
258
 
# File 'ext/rbczmq/message.c', line 252

static VALUE rb_czmq_message_print(VALUE obj)
{
    ZmqGetMessage(obj);
    ZmqReturnNilUnlessOwned(message);
    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

Returns:

  • (Boolean) 


161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'ext/rbczmq/message.c', line 161

static VALUE rb_czmq_message_push(VALUE obj, VALUE frame_obj)
{
    int rc = 0;
    errno = 0;
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);
    ZmqGetFrame(frame_obj);
    ZmqAssertFrameOwnedNoMessage(frame);

    rc = zmsg_push(message->message, frame->frame);
    ZmqAssert(rc);
    frame->message = message;
    frame->flags &= ~ZMQ_FRAME_OWNED;
    zlist_push(message->frames, (void*)frame_obj);
    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

Returns:

  • (Boolean) 


373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
 
# File 'ext/rbczmq/message.c', line 373

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

    /* keep zlist of frame ruby objects in sync with message's frame list */
    zframe_t* zframe = zmsg_first(message->message);
    VALUE frame_object = rb_czmq_alloc_frame(zframe);
    ZmqGetFrame(frame_object);
    frame->flags &= ~ZMQ_FRAME_OWNED;
    frame->message = message;
    zlist_push(message->frames, (void*)frame_object);

    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

Returns:

  • (nil) 


343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
 
# File 'ext/rbczmq/message.c', line 343

static VALUE rb_czmq_message_remove(VALUE obj, VALUE frame_obj)
{
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);
    ZmqGetFrame(frame_obj);

    /* remove from message and our list of frame objects */
    zmsg_remove(message->message, frame->frame);
    zlist_remove(message->frames, (void*)frame_obj);

    /* removing from message does not destroy the frame,
       therefore, we take ownership of the frame at this point */
    frame->message = NULL;
    frame->flags |= ZMQ_FRAME_OWNED;

    return Qnil;
}

#size ⇒ Fixnum

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

Returns:

  • (Fixnum) 


119
120
121
122
123
124
 
# File 'ext/rbczmq/message.c', line 119

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

#to_a ⇒ Array

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")]

Returns:

  • (Array) 


702
703
704
705
706
707
708
709
710
711
712
713
714
 
# File 'ext/rbczmq/message.c', line 702

static VALUE rb_czmq_message_to_a(VALUE obj)
{
    VALUE ary;
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);
    ary = rb_ary_new2(zlist_size(message->frames));
    VALUE frame_obj = (VALUE)zlist_first(message->frames);
    while (frame_obj) {
        rb_ary_push(ary, frame_obj);
        frame_obj = (VALUE)zlist_next(message->frames);
    }
    return ary;
}

#unwrap ⇒ ZMQ::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

Returns:



515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
 
# File 'ext/rbczmq/message.c', line 515

static VALUE rb_czmq_message_unwrap(VALUE obj)
{
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);

    /* reimplemented the zmsg_unwrap function for simpler logic: */
    zframe_t *zframe = zmsg_pop(message->message);
    VALUE frame_obj = 0;
    if (zframe != NULL) {
        frame_obj = (VALUE)zlist_pop(message->frames);
    }

    zframe_t *empty = zmsg_first(message->message);
    if (zframe_size(empty) == 0) {
        empty = zmsg_pop(message->message);
        zframe_destroy (&empty);
        zlist_pop(message->frames);
    }
    
    {
        ZmqGetFrame(frame_obj);
        frame->message = NULL;
        frame->flags |= ZMQ_FRAME_OWNED;
    }
    return frame_obj ? frame_obj : Qnil;
}

#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

Returns:

  • (nil) 


468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
 
# File 'ext/rbczmq/message.c', line 468

static VALUE rb_czmq_message_wrap(VALUE obj, VALUE frame_obj)
{
    errno = 0;
    ZmqGetMessage(obj);
    ZmqAssertMessageOwned(message);

    {
        ZmqGetFrame(frame_obj);
        ZmqAssertFrameOwned(frame);
        zmsg_wrap(message->message, frame->frame);
        frame->flags &= ~ZMQ_FRAME_OWNED;
        frame->message = message;
    }

    /* keep frame objects list in sync. Two frames have been added. frame_obj from above
       and a new one for the empty frame. */
    {
        zmsg_first(message->message);
        zframe_t* empty_frame = zmsg_next(message->message);

        VALUE empty_frame_object = rb_czmq_alloc_frame(empty_frame);
        ZmqGetFrame(empty_frame_object);
        frame->flags &= ~ZMQ_FRAME_OWNED;
        frame->message = message;

        zlist_push(message->frames, (void*)empty_frame_object);
        zlist_push(message->frames, (void*)frame_obj);
    }
    return Qnil;
}