Class: XS::ManagedMessage

Inherits:
Message
  • Object
show all
Defined in:
lib/ffi-rxs/message.rb

Overview

A subclass of #Message that includes finalizers for deallocating native memory when this object is garbage collected. Note that on certain Ruby runtimes the use of finalizers can add 10s of microseconds of overhead for each message. The convenience comes at a price.

The constructor optionally takes a string as an argument. It will copy this string to native memory in preparation for transmission. So, don’t pass a string unless you intend to send it. Internally it calls #copy_in_string.

Call #close to release buffers when you have not passed this on to Socket#send. That method calls #close on your behalf.

When you are done using a received message object, just let it go out of scope to release the memory. During the next garbage collection run it will call the equivalent of #LibXS.xs_msg_close to release all buffers. Obviously, this automatic collection of message objects comes at the price of a larger memory footprint (for the finalizer proc object) and lower performance. If you wanted blistering performance, Ruby isn’t there just yet.

As noted above, for sent objects the underlying library will call close for you.

Instance Method Summary collapse

Methods inherited from Message

#address, #copy, #copy_in_string, #copy_out_string, create, #data, #initialize, #move, msg_size, #size

Constructor Details

This class inherits a constructor from XS::Message

Instance Method Details

#close ⇒ Object

Manually release the message struct and its associated data buffer.

Returns:

  • 0 if successful

  • -1 if unsuccessful



270
271
272
273
274
 
# File 'lib/ffi-rxs/message.rb', line 270

def close
  rc = super()
  remove_finalizer
  rc
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.

Parameters:

  • bytes
  • length

Returns:

  • 0 if successful

  • -1 if unsuccessful



256
257
258
259
260
261
262
263
 
# File 'lib/ffi-rxs/message.rb', line 256

def copy_in_bytes bytes, len
  rc = super(bytes, len)
  
  # make sure we have a way to deallocate this memory if the object goes
  # out of scope
  define_finalizer
  rc
end