DarkSideSync is a Lua helper module for asynchroneous callbacks from other libraries.
Lua is single-threaded by nature and hence working with multithreaded libraries is a complex matter. DarkSideSync aim is to make using asynchroneous libraries (managing their own threadpools) simple.
DarkSideSync takes away the complexity of messages queues, locking, synchronization, etc. because it implements them once and has a thread safe API to perform all those tasks, and notify Lua of incoming threads/data. It is a regular Lua module (C library) that can be loaded from Lua (no C-side dependencies/linking for any libraries using DarkSideSync) and it supports many libraries to consume its services simultaneously.
It can only work with libraries designed to work with DarkSideSync. Check out the library source, specifically darksidesync_api.h on how to do that. Additionally use darksidesync_aux.c to get up and running with DarkSideSync quickly (just an include of this file will get you 95% done).
To use the DarkSideSync library from Lua there are 2 options
- do not use notifications, but regularly call poll to check for incoming data
- use the UDP notification mechanism (a LuaSocket implementation is available in the dss module).
The latter has UDP networking overhead but has some advantages; works with any network library and
allows the application to 'go to sleep' in a network
select() call. Additionally a UDP socket
has the advantage (over a filehandle) that it works on (almost) every platform.
In cases with a high number of callbacks the polling method is considered the better solution.
If you'll be using LuaSocket, then you can probably use the dss module which has a LuaSocket specific abstraction on top of this darksidesync core module.
- Release: Version 1.0, DarkSideSync.
- Copyright: 2012-2013 Thijs Schreijer, DarkSideSync is free software under the MIT/X11 license
|darksidesync_api.h ()||Contains the complete C-side API.|
|darksidesync_aux.c ()||Contains the core client implementation code.|
|setport (port)||Sets the UDP port for notifications.|
|getport ()||Returns the UDP port currently in use for notifications.|
|poll ()||Gets the next item from the darksidesync queue.|
|queuesize ()||Returns the current size of the darksidesync queue.|
|waitingthread_callback (...)||Callback function to set the results of an async callback.|
- darksidesync_api.h ()
- Contains the complete C-side API. See API header file darksidesync_api.h.
- darksidesync_aux.c ()
- Contains the core client implementation code. An implementation of the C-side API (darksidesync_aux.c and darksidesync_aux.h) is available. This implementation should suffice for most usecases. Just copy the file into your project and include it (make sure to read the notes on linking in darksidesync_api.h ).
- setport (port)
Sets the UDP port for notifications. For every item delivered in the
darksidesync queue a notification will be sent. The IP address the notification
will be send to will always be
- port UDP port number to use for notification packets. A value from 0 to 65535, where 0 will disable notifications.
1 if successfull, or
nil + error msgif it failed
- getport ()
Returns the UDP port currently in use for notifications.
UDP portnumber in use (1-65535), or 0 if notifications are disabled
- poll ()
Gets the next item from the darksidesync queue.
If you use the UDP notifications, you MUST also read from the UDP socket to
clear the received packet from the socket buffer.
NOTE: some of the return values will be generated by the client library (that is using darksidesync to get its data delivered to the Lua state) and other return values will be inserted by darksidesync.
- (by DSS) queuesize of remaining items (or -1 if there was nothing on the queue to begin with)
- (by client) Lua callback function to handle the data
- Table with arguments for the Lua callback, this contains (by client library) any other parameters as delivered by the async callback. Optionally, if the async thread requires a result to be returned, a waitingthread_callback function (by DSS) is inserted at position 1 (but only if the async callback expects Lua to deliver a result, in this case the async callback thread will be blocked until the waitingthread_callback is called)
local runcallbacks() local count, callback, args = darksidesync.poll() if count == -1 then return end -- queue was empty, nothing to do callback(unpack(args)) -- execute callback if count > 0 then print("there is more to do; " .. tostring(count) .. " items are still in the queue.") else print("We're done for now.") end end
- queuesize ()
Returns the current size of the darksidesync queue.
number of items in the queue
- waitingthread_callback (...)
Callback function to set the results of an async callback. The 'waiting-thread' callback is collected from
the poll method in case a background thread is blocked and waiting for a result.
Call this function with the results to return to the async callback.
- ... parameters to be delivered to the async callback. This depends on what the client library expects
depends on client library implementation