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).



317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'ext/iodine/iodine_websocket.c', line 317

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 asynchronously, 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`.



293
294
295
296
297
298
299
300
301
302
 
# File 'ext/iodine/iodine_websocket.c', line 293

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.



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

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;
}

#conn_id ⇒ 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.



169
170
171
172
 
# File 'ext/iodine/iodine_websocket.c', line 169

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

#count ⇒ Object

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



147
148
149
150
 
# File 'ext/iodine/iodine_websocket.c', line 147

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).



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
 
# File 'ext/iodine/iodine_websocket.c', line 207

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

The block of code will be executed asynchronously, to avoid having two blocks of code running at the same time and minimizing race conditions when using multilple threads.



269
270
271
272
273
274
275
276
277
278
279
 
# File 'ext/iodine/iodine_websocket.c', line 269

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;
}

#has_pending? ⇒ Boolean

Returns a weak indication as to the state of the socket’s buffer. If the server has data in the buffer that wasn’t written to the socket, ‘has_pending?` will return `true`, otherwise `false` will be returned.

Returns:

  • (Boolean) 


157
158
159
160
 
# File 'ext/iodine/iodine_websocket.c', line 157

static VALUE iodine_ws_has_pending(VALUE self) {
  intptr_t uuid = get_uuid(self);
  return sock_packets_pending(uuid) ? Qtrue : Qfalse;
}

#on_close ⇒ Object

Please implement your own callback for this event.



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

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

#on_open ⇒ Object

Please implement your own callback for this event.



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

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

#on_ready ⇒ Object

Please implement your own callback for this event.



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

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

#on_shutdown ⇒ Object

Please implement your own callback for this event.



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

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.



169
170
171
172
 
# File 'ext/iodine/iodine_websocket.c', line 169

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 ‘true` on success or `false if the websocket was closed or an error occurred.

‘write` will return immediately UNLESS resources are insufficient. If the global `write` buffer is full, `write` will block until a buffer “packet” becomes available and can be assigned to the socket.



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'ext/iodine/iodine_websocket.c', line 130

static VALUE iodine_ws_write(VALUE self, VALUE data) {
  Check_Type(data, T_STRING);
  ws_s *ws = get_ws(self);
  // if ((void *)ws == (void *)0x04 || (void *)data == (void *)0x04 ||
  //     RSTRING_PTR(data) == (void *)0x04)
  //   fprintf(stderr, "iodine_ws_write: self = %p ; data = %p\n"
  //                   "\t\tString ptr: %p, String length: %lu\n",
  //           (void *)ws, (void *)data, RSTRING_PTR(data), RSTRING_LEN(data));
  if (!ws || ((protocol_s *)ws)->service != WEBSOCKET_ID_STR)
    return Qfalse;
  websocket_write(ws, RSTRING_PTR(data), RSTRING_LEN(data),
                  rb_enc_get(data) == UTF8Encoding);
  return Qtrue;
}