Lubyk networking and scheduling 
Single-threaded, fast and predictable scheduling with nanosecond precision.
MIT license © Gaspard Bucher 2014.
Installation
With luarocks:
$ luarocks install lens
Dependencies
.VERSION = '1.0.0'
Current version respecting semantic versioning.
.DEPENDS = {
"lua >= 5.1, < 5.3"
Compatible with Lua 5.1, 5.2 and LuaJIT
'lub >= 1.0.3, < 2.0'
Uses Lubyk base library
}
Scheduling
Note that all scheduling functions operate by using coroutine.yield and it is possible to use these equivalent methods instead.
.run (func)
Enter event loop. This is equivalent to creating a lens.Scheduler and calling run on it with some differences:
- The initial call to
lens.runnever returns - Repeated calls to this function are ignored which this means that code after
lens.runis executed.
This is typically used for live coding.
.halt ()
Stop scheduler and exit. Usage:
lens.halt()
-- is the same as
coroutine.yield('halt')
.sleep (sec)
Sleep for sec seconds (precision depends on OS). Using nanosecond for precise sleep on linux and macosx. note that this should not be used to create a precise timer: use lens.Timer for non-drifting timers.
Usage:
lens.sleep(0.5)
-- is the same as
coroutine.yield('sleep', sec)
.waitRead (fd)
Wait until the filedescriptor fd is ready for reading. Since some pollers are edge based, make sure that fd is not readable before calling this.
this function simply does:
lens.waitRead(fd)
-- is the same as
coroutine.yield('read', fd)
.waitWrite (fd)
Wait until the filedescriptor fd is ready for writing. Since some pollers are edge based, make sure that fd is not writeable before calling this.
this function simply does:
lens.waitWrite(fd)
-- is the same as
coroutine.yield('write', fd)
.elapsed ()
Get monotonic elapsed time since some arbitrary point in time. This timer is as precise as the OS permits and does not jump forward or back. When a computer is connected to atomic clocks with ntp protocol, this clock is adjusted by altering it's speed and should be very precise but can have some jitter.
Uses mach_absolute_time on macosx, clock_gettime (CLOCK_MONOTONIC) on linux and QueryPerformanceCounter on windows.
Helpers
.class (name, tbl, skip_lub)
This is like lub.class but with class reloading support. Should only be used during development. If skip_lub is true, do not call lub.class and alter table setup (this is needed when wrapping class objects as library items).
.sched ()
Return default scheduler (the one used in lens.run and by lens.FileWatch or lens.Thread when called without a coroutine running).
Classes
File
A simple OS file wrapper which can return file descriptors for read/write/events.
FileWatch
Watches a file and executes the changed callback if the content changes. Uses kevent or other OS optimized notification so that listening to files takes as few resources as possible.
Finalizer
This object executes the provided method when it is garbage collected.
Poller
Normally, end users do not interact directly with the poller. It is used internally by lens.Scheduler to wait on file descriptors and sleep. This poller uses fast poll API and nanosleep for precise operation.
Popen
PopenTODO MISSING DOCUMENTATION
PopenTODO MISSING DOCUMENTATION
PopenTODO implement bidirectional pipes.
Scheduler
TODO Missing documentation on yield operations
CallbackFIXME give some time to GUI ?
SchedulerTODO Missing documentation on yield operations
#loopTODO MISSING DOCUMENTATION
CallbackTODO Should we restart an erroring thread right away ??
Socket
Thread
Thread garbage collection
#killTODO MISSING DOCUMENTATION
Timer
The Timer contains a callback to execute a function at regular intervals. This timer does not drift (uses OS monotonic clock).