Class: ZMQ::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/ffi-rzmq/message.rb,
lib/ffi-rzmq/message.rb

Overview

class Message

Direct Known Subclasses

ManagedMessage

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message = nil) ⇒ Message

Returns a new instance of Message.



95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/ffi-rzmq/message.rb', line 95

def initialize message = nil
  # allocate our own pointer so that we can tell it to *not* zero out
  # the memory; it's pointless work since the library is going to
  # overwrite it anyway.
  @pointer = FFI::MemoryPointer.new Message.msg_size, 1, false

  if message
    copy_in_string message
  else
    # initialize an empty message structure to receive a message
    result_code = LibZMQ.zmq_msg_init @pointer
    raise unless Util.resultcode_ok?(result_code)
  end
end

Class Method Details

.create(message = nil) ⇒ Object

Recommended way to create a standard message. A Message object is returned upon success, nil when allocation fails.



91
92
93
 
# File 'lib/ffi-rzmq/message.rb', line 91

def self.create message = nil
  new(message) rescue nil
end

.msg_size ⇒ Object 



198
 
# File 'lib/ffi-rzmq/message.rb', line 198

def self.msg_size() @msg_size; end

Instance Method Details

#address ⇒ Object Also known as: pointer

Provides the memory address of the zmq_msg_t struct. Used mostly for passing to other methods accessing the underlying library that require a real data address.



141
142
143
 
# File 'lib/ffi-rzmq/message.rb', line 141

def address
  @pointer
end

#close ⇒ Object

Manually release the message struct and its associated data buffer.

Only releases the buffer a single time. Subsequent calls are no ops.



183
184
185
186
187
188
189
190
191
192
 
# File 'lib/ffi-rzmq/message.rb', line 183

def close
  rc = 0

  if @pointer
    rc = LibZMQ.zmq_msg_close @pointer
    @pointer = nil
  end

  rc
end

#copy(source) ⇒ Object 



146
147
148
 
# File 'lib/ffi-rzmq/message.rb', line 146

def copy source
  LibZMQ.zmq_msg_copy @pointer, source
end

#copy_in_bytes(bytes, len) ⇒ Object

Makes a copy of len bytes from the ruby string bytes. Library handles deallocation of the native memory buffer.

Can only be initialized via #copy_in_string or #copy_in_bytes once.



126
127
128
129
130
131
132
133
134
135
 
# File 'lib/ffi-rzmq/message.rb', line 126

def copy_in_bytes bytes, len
  data_buffer = LibC.malloc len
  # writes the exact number of bytes, no null byte to terminate string
  data_buffer.write_string bytes, len

  # use libC to call free on the data buffer; earlier versions used an
  # FFI::Function here that called back into Ruby, but Rubinius won't
  # support that and there are issues with the other runtimes too
  LibZMQ.zmq_msg_init_data @pointer, data_buffer, len, LibC::Free, nil
end

#copy_in_string(string) ⇒ Object

Makes a copy of the ruby string into a native memory buffer so that libzmq can send it. The underlying library will handle deallocation of the native memory buffer.

Can only be initialized via #copy_in_string or #copy_in_bytes once.



116
117
118
119
 
# File 'lib/ffi-rzmq/message.rb', line 116

def copy_in_string string
  string_size = string.respond_to?(:bytesize) ? string.bytesize : string.size
  copy_in_bytes string, string_size if string
end

#copy_out_string ⇒ Object

Returns the data buffer as a string.

Note: If this is binary data, it won’t print very prettily.



173
174
175
 
# File 'lib/ffi-rzmq/message.rb', line 173

def copy_out_string
  data.read_string(size)
end

#data ⇒ Object

Returns a pointer to the data buffer. This pointer should never be freed. It will automatically be freed when the message object goes out of scope and gets garbage collected.



165
166
167
 
# File 'lib/ffi-rzmq/message.rb', line 165

def data
  LibZMQ.zmq_msg_data @pointer
end

#get(property) ⇒ Object 



203
204
205
 
# File 'lib/ffi-rzmq/message.rb', line 203

def get(property)
  LibZMQ.zmq_msg_get(@pointer, property)
end

#more? ⇒ Boolean

Returns true if this message has additional parts coming.

Returns:

  • (Boolean) 


209
210
211
 
# File 'lib/ffi-rzmq/message.rb', line 209

def more?
  Util.resultcode_ok?(get(MORE))
end

#move(source) ⇒ Object 



150
151
152
 
# File 'lib/ffi-rzmq/message.rb', line 150

def move source
  LibZMQ.zmq_msg_move @pointer, source
end

#set(property, value) ⇒ Object 



213
214
215
 
# File 'lib/ffi-rzmq/message.rb', line 213

def set(property, value)
  LibZMQ.zmq_msg_set(@pointer, property, value)
end

#size ⇒ Object

Provides the size of the data buffer for this zmq_msg_t C struct.



156
157
158
 
# File 'lib/ffi-rzmq/message.rb', line 156

def size
  LibZMQ.zmq_msg_size @pointer
end