Module: Iodine::Websocket

Defined in:
ext/iodine/iodine_websocket.c

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.defer(ws_uuid) ⇒ Object

Schedules a block of code to run for the specified connection at a later time, (if the connection is open) and while preventing concurent code from running for the same connection object.

The block of code will receive the connection’s object. i.e.

Iodine::Websocket.defer(uuid) {|ws| ws.write "I'm doing this" }

On success returns the block, otherwise (connection invalid) returns ‘false`. A sucessful event registration doesn’t guaranty that the block will be called (the connection might close between the event registration and the execution).



285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'ext/iodine/iodine_websocket.c', line 285

static VALUE iodine_class_defer(VALUE self, VALUE ws_uuid) {
  intptr_t fd = FIX2LONG(ws_uuid);
  if (!sock_isvalid(fd))
    return Qfalse;
  // requires a block to be passed
  rb_need_block();
  VALUE block = rb_block_proc();
  if (block == Qnil)
    return Qfalse;
  Registry.add(block);

  server_task(fd, iodine_perform_defer, (void *)block, iodine_defer_fallback);
  return block;
}

.each ⇒ Object

Runs the required block for each dynamic protocol connection.

Tasks will be performed within each connections lock, so no connection will have more then one task being performed at the same time (similar to #defer).

Also, unlike Iodine.run, the block will not be called unless the connection remains open at the time it’s execution is scheduled.

Always returns ‘self`.



261
262
263
264
265
266
267
268
269
270
 
# File 'ext/iodine/iodine_websocket.c', line 261

static VALUE iodine_ws_class_each(VALUE self) {
  // requires a block to be passed
  rb_need_block();
  VALUE block = rb_block_proc();
  if (block == Qnil)
    return Qfalse;
  Registry.add(block);
  iodine_ws_run_each(-1, block);
  return self;
}

Instance Method Details

#close ⇒ Object

Closes the websocket connection. The connection is only closed after existing data in the outgoing buffer is sent.



111
112
113
114
115
116
117
 
# File 'ext/iodine/iodine_websocket.c', line 111

static VALUE iodine_ws_close(VALUE self) {
  ws_s *ws = get_ws(self);
  if (((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
    return Qfalse;
  websocket_close(ws);
  return self;
}

#count ⇒ Object

Returns the number of active websocket connections (including connections that are in the process of closing down).



131
132
133
134
 
# File 'ext/iodine/iodine_websocket.c', line 131

static VALUE iodine_ws_count(VALUE self) {
  ws_s *ws = get_ws(self);
  return LONG2FIX(websocket_count(ws));
}

#defer(*args) ⇒ Object

Schedules a block of code to execute at a later time, if the connection is still open and while preventing concurent code from running for the same connection object.

An optional ‘uuid` argument can be passed along, so that the block of code will run for the requested connection rather then this connection.

Careful*: as this might cause this connection’s object to run code concurrently when data owned by this connection is accessed from within the block of code.

On success returns the block, otherwise (connection invalid) returns ‘false`. A sucessful event registration doesn’t guaranty that the block will be called (the connection might close between the event registration and the execution).



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'ext/iodine/iodine_websocket.c', line 181

static VALUE iodine_defer(int argc, VALUE *argv, VALUE self) {
  intptr_t fd;
  // check arguments.
  if (argc > 1)
    rb_raise(rb_eArgError, "this function expects no more then 1 (optional) "
                           "argument.");
  else if (argc == 1) {
    Check_Type(*argv, T_FIXNUM);
    fd = FIX2LONG(*argv);
    if (!sock_isvalid(fd))
      return Qfalse;
  } else
    fd = iodine_get_fd(self);
  // requires a block to be passed
  rb_need_block();
  VALUE block = rb_block_proc();
  if (block == Qnil)
    return Qfalse;
  Registry.add(block);

  server_task(fd, iodine_perform_defer, (void *)block, iodine_defer_fallback);
  return block;
}

#each ⇒ Object

Performs a block of code for each websocket connection. The function returns the block of code.

The block of code should accept a single variable which is the websocket connection.

i.e.:

def on_message data
  msg = data.dup; # data will be overwritten once the function exists.
  each {|ws| ws.write msg}
end



238
239
240
241
242
243
244
245
246
247
248
 
# File 'ext/iodine/iodine_websocket.c', line 238

static VALUE iodine_ws_each(VALUE self) {
  // requires a block to be passed
  rb_need_block();
  VALUE block = rb_block_proc();
  if (block == Qnil)
    return Qnil;
  Registry.add(block);
  intptr_t fd = get_uuid(self);
  iodine_ws_run_each(fd, block);
  return block;
}

#on_close ⇒ Object

Please implement your own callback for this event.



376
 
# File 'ext/iodine/iodine_websocket.c', line 376

static VALUE empty_func(VALUE self) { return Qnil; }

#on_open ⇒ Object

Please implement your own callback for this event.



376
 
# File 'ext/iodine/iodine_websocket.c', line 376

static VALUE empty_func(VALUE self) { return Qnil; }

#on_shutdown ⇒ Object

Please implement your own callback for this event.



376
 
# File 'ext/iodine/iodine_websocket.c', line 376

static VALUE empty_func(VALUE self) { return Qnil; }

#uuid ⇒ Object

Returns a connection’s UUID which is valid for **this process** (not a machine or internet unique value).

This can be used together with a true process wide UUID to uniquely identify a connection across the internet.



143
144
145
146
 
# File 'ext/iodine/iodine_websocket.c', line 143

static VALUE iodine_ws_uuid(VALUE self) {
  intptr_t uuid = get_uuid(self);
  return LONG2FIX(uuid);
}

#write(data) ⇒ Object

Writes data to the websocket. Returns ‘self` (the websocket object).



120
121
122
123
124
125
126
127
 
# File 'ext/iodine/iodine_websocket.c', line 120

static VALUE iodine_ws_write(VALUE self, VALUE data) {
  ws_s *ws = get_ws(self);
  if (((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
    return Qfalse;
  websocket_write(ws, RSTRING_PTR(data), RSTRING_LEN(data),
                  rb_enc_get(data) == UTF8Encoding);
  return self;
}