Class: Iodine::PubSub::Engine

Inherits:
Object
  • Object
show all
Defined in:
lib/iodine/pubsub.rb,
ext/iodine/iodine_pubsub.c

Overview

The Engine class makes it easy to use leverage Iodine’s pub/sub system using external services.

Iodine comes with two built-in engines:

  • ‘Iodine::PubSub::Engine::CLUSTER` will distribute messages to all subscribers in the process cluster.

  • ‘Iodine::PubSub::Engine::SINGLE_PROCESS` will distribute messages to all subscribers sharing the same process.

Engine instances should be initialized only after Iodine started running (or the ‘fork`ing of the engine’s connection will introduce communication issues).

For this reason, the best approcah to initialization would be:

class MyEngineClass < Iodine::PubSub::Engine
     # ...
end

Iodine.run do
   MyEngine = MyEngineClass.new
end

Engine child classes MUST override the #subscribe, #unsubscribe and #publish in order to perform this actions using the backend service (i.e. using Redis).

Once an Engine instance receives a message from the backend service, it should forward the message to the Iodine distribution layer using the #distribute method.

Iodine will than distribute the message to all registered clients.

IMPORTANT:

Connections shouldn’t call any of the Engine or Iodine::PubSub methods directly, since connections might be disconnected at any time, at which point their memory will become corrupted or recycled.

The connection pub/sub methods (coming soon) keep the application safe from these risks by performing specific checks for connection related pub/sub actions.

Direct Known Subclasses

RedisEngine

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Object 



374
375
376
377
378
379
380
381
382
 
# File 'ext/iodine/iodine_pubsub.c', line 374

static VALUE engine_initialize(VALUE self) {
  iodine_engine_s *engine;
  Data_Get_Struct(self, iodine_engine_s, engine);
  if (TYPE(self) == T_CLASS) {
    fprintf(stderr, "This sucks...\n");
  }
  engine->handler = self;
  return self;
}

Instance Method Details

#deregister ⇒ Object

This method removes the engine from the pub/sub system.



135
136
137
 
# File 'ext/iodine/iodine_pubsub.c', line 135

static VALUE iodine_engine_deregister(VALUE self) {
  return iodine_engine_deregister2(self, self);
}

#publish(channel, msg) ⇒ Object

Override this method to handle message publishing to the underlying engine (i.e. from Ruby to Redis or from Ruby to MongoDB).

This function will be called by Iodine during pub/sub publication. Don’t call this function from your own code / application.

The function should return ‘true` on success and `nil` or `false` on failure.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
 
# File 'ext/iodine/iodine_pubsub.c', line 66

static VALUE engine_pub_placeholder(VALUE self, VALUE channel, VALUE msg) {
  { /* test for built-in C engines */
    iodine_engine_s *engine;
    Data_Get_Struct(self, iodine_engine_s, engine);
    if (engine->p != &engine->engine) {
      FIOBJ ch = fiobj_str_new(RSTRING_PTR(channel), RSTRING_LEN(channel));
      FIOBJ m = fiobj_str_new(RSTRING_PTR(msg), RSTRING_LEN(msg));
      pubsub_publish(.engine = engine->p, .channel = ch, .message = m);
      fiobj_free(ch);
      fiobj_free(msg);
      return Qtrue;
    }
  }
  return Qnil;
  (void)self;
  (void)msg;
  (void)channel;
}

#register ⇒ Object

This method adds the engine to the pub/sub system, allowing it to recieve system wide notifications.



111
112
113
 
# File 'ext/iodine/iodine_pubsub.c', line 111

static VALUE iodine_engine_register(VALUE self) {
  return iodine_engine_register2(self, self);
}

#reset ⇒ Object

This method resets the engine, (re)sending all the current subscription data as if the #register method was just called.



160
161
162
 
# File 'ext/iodine/iodine_pubsub.c', line 160

static VALUE iodine_engine_reset(VALUE self) {
  return iodine_engine_reset2(self, self);
}

#subscribe(channel, use_pattern) ⇒ Object

Override this method to handle (un)subscription requests.

This function will be called by Iodine during pub/sub (un)subscription. Don’t call this function from your own code / application.

The function should return ‘true` on success and `nil` or `false` on failure.



49
50
51
52
53
54
55
 
# File 'ext/iodine/iodine_pubsub.c', line 49

static VALUE engine_sub_placeholder(VALUE self, VALUE channel,
                                    VALUE use_pattern) {
  return Qnil;
  (void)self;
  (void)channel;
  (void)use_pattern;
}

#unsubscribe(channel, use_pattern) ⇒ Object

Override this method to handle (un)subscription requests.

This function will be called by Iodine during pub/sub (un)subscription. Don’t call this function from your own code / application.

The function should return ‘true` on success and `nil` or `false` on failure.



49
50
51
52
53
54
55
 
# File 'ext/iodine/iodine_pubsub.c', line 49

static VALUE engine_sub_placeholder(VALUE self, VALUE channel,
                                    VALUE use_pattern) {
  return Qnil;
  (void)self;
  (void)channel;
  (void)use_pattern;
}