Class Nanite::Mapper
In: lib/nanite/mapper.rb
Parent: Object

Mappers are control nodes in nanite clusters. Nanite clusters can follow peer-to-peer model of communication as well as client-server, and mappers are nodes that know who to send work requests to agents.

Mappers can reside inside a front end web application written in Merb/Rails and distribute heavy lifting to actors that register with the mapper as soon as they go online.

Each mapper tracks nanites registered with it. It periodically checks when the last time a certain nanite sent a heartbeat notification, and removes those that have timed out from the list of available workers. As soon as a worker goes back online again it re-registers itself and the mapper adds it to the list and makes it available to be called again.

This makes Nanite clusters self-healing and immune to individual node failures.

Methods

new   offline_failsafe?   push   request   run   send_push   send_request   start  

Included Modules

AMQPHelper ConsoleHelper DaemonizeHelper

Constants

DEFAULT_OPTIONS = COMMON_DEFAULT_OPTIONS.merge({ :user => 'mapper', :identity => Identity.generate, :agent_timeout => 15, :offline_redelivery_frequency => 10, :persistent => false, :offline_failsafe => false, :callbacks => {}

Attributes

amq  [R] 
cluster  [R] 
identity  [R] 
job_warden  [R] 
options  [R] 
serializer  [R] 

Public Class methods

Initializes a new mapper and establishes AMQP connection. This must be used inside EM.run block or if EventMachine reactor is already started, for instance, by a Thin server that your Merb/Rails application runs on.

Mapper options:

identity : identity of this mapper, may be any string

format : format to use for packets serialization. Can be :marshal, :json or :yaml or :secure.

              Defaults to Ruby's Marshall format. For interoperability with
              AMQP clients implemented in other languages, use JSON.

              Note that Nanite uses JSON gem,
              and ActiveSupport's JSON encoder may cause clashes
              if ActiveSupport is loaded after JSON gem.

              Also using the secure format requires prior initialization of the serializer, see
              SecureSerializer.init

log_level : the verbosity of logging, can be debug, info, warn, error or fatal.

agent_timeout : how long to wait before an agent is considered to be offline

                  and thus removed from the list of available agents.

log_dir : log file path, defaults to the current working directory.

console : true tells mapper to start interactive console

daemonize : true tells mapper to daemonize

pid_dir : path to the directory where the agent stores its pid file (only if daemonized)

              defaults to the root or the current working directory.

offline_redelivery_frequency : The frequency in seconds that messages stored in the offline queue will be retrieved

                               for attempted redelivery to the nanites. Default is 10 seconds.

persistent : true instructs the AMQP broker to save messages to persistent storage so that they aren‘t lost when the

              broker is restarted. Default is false. Can be overriden on a per-message basis using the request and push methods.

secure : use Security features of rabbitmq to restrict nanites to themselves

prefetch : Sets prefetch (only supported in RabbitMQ >= 1.6) callbacks : A set of callbacks to have code executed on specific events, supported events are :register,

              :unregister and :timeout. Parameter must be a hash with the corresponding events as keys and
              a block as value. The block will get the corresponding nanite's identity and a copy of the
              mapper

Connection options:

vhost : AMQP broker vhost that should be used

user : AMQP broker user

pass : AMQP broker password

host : host AMQP broker (or node of interest) runs on,

           defaults to 0.0.0.0

port : port AMQP broker (or node of interest) runs on,

           this defaults to 5672, port used by some widely
           used AMQP brokers (RabbitMQ and ZeroMQ)

@api :public:

Public Instance methods

Make a nanite request which does not expect a response.

Parameters

type<String>:The dispatch route for the request
payload<Object>:Payload to send. This will get marshalled en route

Options

:selector<Symbol>:Method for selecting an actor. Default is :least_loaded.
  :least_loaded:: Pick the nanite which has the lowest load.
  :all:: Send the request to all nanites which respond to the service.
  :random:: Randomly pick a nanite.
  :rr: Select a nanite according to round robin ordering.
:offline_failsafe<Boolean>:Store messages in an offline queue when all
  the nanites are offline. Messages will be redelivered when nanites come online.
  Default is false unless the mapper was started with the --offline-failsafe flag.
:persistent<Boolean>:Instructs the AMQP broker to save the message to persistent
  storage so that it isnt lost when the broker is restarted.
  Default is false unless the mapper was started with the --persistent flag.

@api :public:

Make a nanite request which expects a response.

Parameters

type<String>:The dispatch route for the request
payload<Object>:Payload to send. This will get marshalled en route

Options

:selector<Symbol>:Method for selecting an actor. Default is :least_loaded.
  :least_loaded:: Pick the nanite which has the lowest load.
  :all:: Send the request to all nanites which respond to the service.
  :random:: Randomly pick a nanite.
  :rr: Select a nanite according to round robin ordering.
:target<String>:Select a specific nanite via identity, rather than using
  a selector.
:offline_failsafe<Boolean>:Store messages in an offline queue when all
  the nanites are offline. Messages will be redelivered when nanites come online.
  Default is false unless the mapper was started with the --offline-failsafe flag.
:persistent<Boolean>:Instructs the AMQP broker to save the message to persistent
  storage so that it isnt lost when the broker is restarted.
  Default is false unless the mapper was started with the --persistent flag.
:intermediate_handler:Takes a lambda to call when an IntermediateMessage
  event arrives from a nanite.  If passed a Hash, hash keys should correspond to
  the IntermediateMessage keys provided by the nanite, and each should have a value
  that is a lambda/proc taking the parameters specified here.  Can supply a key '*'
  as a catch-all for unmatched keys.

Block Parameters for intermediate_handler

key<String>:array of unique keys for which intermediate state has been received
  since the last call to this block.
nanite<String>:nanite which sent the message.
state:most recently delivered intermediate state for the key provided.
job:(optional) — if provided, this parameter gets the whole job object, if there‘s
  a reason to do more complex work with the job.

Block Parameters

:results<Object>:The returned value from the nanite actor.

@api :public:

[Validate]