Class: XS::Context

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

Overview

All sockets exist within a context and a context is passed to the Socket constructor when allocating new sockets.

Also, Sockets should only be accessed from the thread where they were first created. Do not pass sockets between threads; pass in the context and allocate a new socket per thread. If you must use threads, then make sure to execute a full memory barrier (e.g. mutex) as you pass a socket from one thread to the next.

To connect sockets between contexts, use inproc or ipc transport and set up a Crossroads socket between them. This is also the recommended technique for allowing sockets to communicate between threads.

Examples:

Create context and socket

context = XS::Context.create
if context
  socket = context.socket(XS::REQ)
  if socket
    ...
  else
    STDERR.puts "Socket allocation failed"
  end
else
  STDERR.puts "Context allocation failed"
end

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Context) initialize

Initialize context object



41
42
43
44
45
46
47
48
 
# File 'lib/ffi-rxs/context.rb', line 41

def initialize
  @sockets = []
  @context = LibXS.xs_init()
  @pointer = @context
  XS::Util.error_check 'xs_init', (@context.nil? || @context.null?) ? -1 : 0

  define_finalizer
end

Instance Attribute Details

- (Object) context (readonly)

Returns the value of attribute context



33
34
35
 
# File 'lib/ffi-rxs/context.rb', line 33

def context
  @context
end

- (Object) pointer (readonly)

Returns the value of attribute pointer



33
34
35
 
# File 'lib/ffi-rxs/context.rb', line 33

def pointer
  @pointer
end

Class Method Details

+ (Object) create

Factory method to instantiate contexts



36
37
38
 
# File 'lib/ffi-rxs/context.rb', line 36

def self.create
  new() rescue nil
end

Instance Method Details

- (Object) setctxopt(name, value)

Sets options on a context.

It is recommended to use the default for io_threads (which is 1) since most programs will not saturate I/O.

The rule of thumb is to make io_threads equal to the number of gigabits per second that the application will produce.

The io_threads number specifies the size of the thread pool allocated by Crossroads for processing incoming/outgoing messages.

The max_sockets number specifies the number of concurrent sockets that can be used in the context. The default is 512.

Context options take effect only if set with setctxopt() prior to creating the first socket in a given context with socket().

Examples:

Set io_threads context option

rc = context.setctxopt(XS::IO_THREADS, 10)
unless XS::Util.resultcode_ok?(rc)
  XS::raise_error('xs_setctxopt', rc)
end

Parameters:

  • name (Constant) —

    One of XS::IO_THREADS or XS::MAX_SOCKETS.

  • value (Integer)

Returns:

  • 0 when the operation completed successfully.

  • -1 when this operation fails.



79
80
81
82
83
84
85
86
87
 
# File 'lib/ffi-rxs/context.rb', line 79

def setctxopt name, value
  length = 4
  pointer = LibC.malloc length
  pointer.write_int value

  rc = LibXS.xs_setctxopt @context, name, pointer, length
  LibC.free(pointer) unless pointer.nil? || pointer.null?
  rc
end

- (Socket) socket(type)

Allocates a socket for context

Parameters:

  • type (Constant) —

    One of XS::REQ, XS::REP, XS::PUB, XS::SUB, XS::PAIR, XS::PULL, XS::PUSH, XS::DEALER, or XS::ROUTER

Returns:

  • (Socket) —

    when the allocation succeeds

  • nil when call fails



116
117
118
119
120
121
122
123
124
125
 
# File 'lib/ffi-rxs/context.rb', line 116

def socket type
  sock = nil
  begin
    sock = Socket.new @context, type
  rescue ContextError => e
    sock = nil
  end
  
  sock
end

- (Object) terminate

Releases the context and any remaining data associated with past sockets. This will close any sockets that remain open; further calls to those sockets will return -1 to indicate the operation failed.

Returns:

  • 0 for success

  • -1 for failure



96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/ffi-rxs/context.rb', line 96

def terminate
  unless @context.nil? || @context.null?
    remove_finalizer
    rc = LibXS.xs_term @context
    @context = nil
    @sockets = nil
    rc
  else
    0
  end
end