Home
Ratchet Library :: API Reference
API  ·  Manual

Module ratchet

The purpose of the ratchet library is to provide a generic socket control mechanism for large numbers of sockets without using threads or losing the ease of synchronous socket programming. Along with networking, the library provides a sort of kernel to allow side-by-side execution of different streams of logic.

Functions

attach (self, func, ...) Queues a new thread for execution.
attach_background (self, func, ...) Queues a new thread for execution.
get_method (self) Returns the polling method used behind-the-scenes by libevent.
loop (self) Starts the main loop.
new () Constructs and returns a new ratchet object.
pause (self) Pauses the current thread indefinitely.
running_thread (self) Returns the Lua thread object that is currently running, or nil for the main thread.
set_error_handler (self, func, ...) Sets the new error handler for threads.
thread_space (self, premade) Returns a table that is specific to the currently-running thread that can be used as scratch-space for thread-scope data.
timer (self, seconds) Pauses the current thread for the given period.
unpause (self, thread, ...) Unpauses the given thread.
wait_all (self, threads) Pauses the current thread until all threads listed in the given table have completed their execution either normally or by error.


Functions

attach (self, func, ...)
Queues a new thread for execution. The thread calls func and gives it any extra arguments as its parameters. The thread is not started by this method, instead it is started on next iteration of the loop. All threads attached with this method must be completed before loop() will finish.

Parameters

  • self: the ratchet object.
  • func: the function to run in the thread.
  • ...: extra parameters to function.

Return value:

a Lua thread object.
attach_background (self, func, ...)
Queues a new thread for execution. The thread calls func and gives it any extra arguments as its parameters. The thread is not started by this method, instead it is started on next iteration of the loop. Threads attached with this method as opposed to attach() will be destroyed when loop() finishes, whether completed or not.

Parameters

  • self: the ratchet object.
  • func: the function to run in the thread.
  • ...: extra parameters to function.

Return value:

a Lua thread object.
get_method (self)
Returns the polling method used behind-the-scenes by libevent.

Parameters

  • self: the ratchet object.

Return value:

a string identifying the kernel event mechanism (kqueue, epoll, etc.).
loop (self)
Starts the main loop. Every iteration of this loop runs all new threads, runs all recently unpaused threads, runs all threads that are done waiting on others, and finally starts waiting for and handling network/socket events. The loop will continue until all threads created with attach() are completed.

Parameters

  • self: the ratchet object.
new ()
Constructs and returns a new ratchet object. This also creates a new libevent control structure that is freed when the object is collected.

Return value:

a new ratchet object.
pause (self)
Pauses the current thread indefinitely. The thread must be resumed by a call to unpause() from another thread.

Parameters

  • self: the ratchet object.

Return value:

any extra arguments passed to unpause() from other thread.
running_thread (self)
Returns the Lua thread object that is currently running, or nil for the main thread.

Parameters

  • self: the ratchet object.

Return value:

thread object or nil.
set_error_handler (self, func, ...)
Sets the new error handler for threads. The scope of the error handler depends on where this method is called. Calling from the main thread will use this handler as the default. Error handlers set in threads apply only to that thead. Extra arguments to this function are given to the handler function. The last parameter in the call will be the error object.

Parameters

  • self: the ratchet object.
  • func: the function to call.
  • ...: extra parameters to the function, before error object.
thread_space (self, premade)
Returns a table that is specific to the currently-running thread that can be used as scratch-space for thread-scope data. This table is not created until the first time this method is called for in thread.

Parameters

  • self: the ratchet object.
  • premade: optionally pass in a pre-existing object to be stored as the thread's scratch space instead of the default a new table.

Return value:

a table specific to the current thread.
timer (self, seconds)
Pauses the current thread for the given period.

Parameters

  • self: the ratchet object.
  • seconds: resume thread after this many seconds elapse.
unpause (self, thread, ...)
Unpauses the given thread. The paused thread will resume on next iteration of the main loop. Extra parameters to this function will be given to the paused thread as return values from pause().

Parameters

  • self: the ratchet object.
  • thread: the thread to unpause.
  • ...:
wait_all (self, threads)
Pauses the current thread until all threads listed in the given table have completed their execution either normally or by error.

Parameters

  • self: the ratchet object.
  • threads: table containing threads to wait for.