Class: XS::Context

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

Overview

Recommended to use the default for io_threads since most programs will not saturate I/O.

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

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

Returns a context object when allocation succeeds. It’s necessary for passing to the #Socket constructor when allocating new sockets. All sockets live within a context.

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.

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

Methods included from Util

bind_to_random_tcp_port, errno, error_string, resultcode_ok?, version

Constructor Details

#initialize ⇒ Context

Use the factory method Context#create to make contexts.



54
55
56
57
58
59
60
61
 
# File 'lib/ffi-rxs/context.rb', line 54

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

  define_finalizer
end

Instance Attribute Details

#context ⇒ Object (readonly)

Returns the value of attribute context.



46
47
48
 
# File 'lib/ffi-rxs/context.rb', line 46

def context
  @context
end

#pointer ⇒ Object (readonly)

Returns the value of attribute pointer.



46
47
48
 
# File 'lib/ffi-rxs/context.rb', line 46

def pointer
  @pointer
end

Class Method Details

.create ⇒ Object 



48
49
50
 
# File 'lib/ffi-rxs/context.rb', line 48

def self.create
  new() rescue nil
end

Instance Method Details

#setctxopt(name, value, length = nil) ⇒ Object

Set options on this context.

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

Valid name values that take a numeric value are:

XS::IO_THREADS
XS::MAX_SOCKETS

Returns 0 when the operation completed successfully. Returns -1 when this operation failed.

With a -1 return code, the user must check XS.errno to determine the cause.

rc = context.setctxopt(XS::IO_THREADS, 10)
XS::Util.resultcode_ok?(rc) ? puts("succeeded") : puts("failed")



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

def setctxopt name, value, length = nil
  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(type) ⇒ Object

Short-cut to allocate a socket for a specific context.

Takes several type values:

#XS::REQ
#XS::REP
#XS::PUB
#XS::SUB
#XS::PAIR
#XS::PULL
#XS::PUSH
#XS::DEALER
#XS::ROUTER

Returns a #XS::Socket when the allocation succeeds, nil if it fails.



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

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

#terminate ⇒ Object

Call to release 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.



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

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