Module darksidesync

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.

Check here for an overview.

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

  1. do not use notifications, but regularly call poll to check for incoming data
  2. 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.

Info:

  • Release: Version 1.0, DarkSideSync.
  • Copyright: 2012-2013 Thijs Schreijer, DarkSideSync is free software under the MIT/X11 license

C-side DarkSideSync API

darksidesync_api.h () Contains the complete C-side API.
darksidesync_aux.c () Contains the core client implementation code.

Lua-side DarkSideSync API

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.


C-side DarkSideSync API

C-side DarkSideSync API. This section covers the darksidesync API from the C-side. It is not separately documented, but only in the code files.
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 ).

Lua-side DarkSideSync API

Lua-side DarkSideSync API. This section covers the darksidesync API from the Lua-side
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 localhost (loopback adapter).

Parameters:

  • port UDP port number to use for notification packets. A value from 0 to 65535, where 0 will disable notifications.

Returns:

    1 if successfull, or nil + error msg if it failed

see also:

getport ()
Returns the UDP port currently in use for notifications.

Returns:

    UDP portnumber in use (1-65535), or 0 if notifications are disabled

see also:

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.

Returns:

  1. (by DSS) queuesize of remaining items (or -1 if there was nothing on the queue to begin with)
  2. (by client) Lua callback function to handle the data
  3. 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)

Usage:

    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.

Returns:

    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:

  • ... parameters to be delivered to the async callback. This depends on what the client library expects

Returns:

    depends on client library implementation

see also:

generated by LDoc 1.3