Code refactoring.
[lua-llthreads2.git] / README.md
1 lua-llthreads2
2 ==============
3 [![Build Status](https://travis-ci.org/moteus/lua-llthreads2.png?branch=master)](https://travis-ci.org/moteus/lua-llthreads2)
4
5 This is full dropin replacement for [llthreads](https://github.com/Neopallium/lua-llthreads) library.
6
7 ##Incompatibility list with origin llthreads library
8 * does not support Lua 5.0
9 * does not support ffi interface (use Lua C API for LuaJIT)
10 * returns nil instead of false on error
11 * start method returns self instead of true on success
12
13 ##Additional
14 * thread:join() method support zero timeout to check if thread alive (does not work on Windows with pthreads)
15 * thread:join() method support arbitrary timeout on Windows threads
16 * set_logger function allow logging errors (crash Lua VM) in current llthread's threads
17 * thread:start() has additional parameter which control in which thread child Lua VM will be destroyed
18 * allow pass cfunctions to child thread (e.g. to initialize Lua state) (experemental)
19
20 ##Usage
21
22 ### Use custom logger
23 In this example I use [lua-log](https://github.com/moteus/lua-log) library.
24 ``` Lua
25 -- This is child thread.
26 local llthreads = require "llthreads"
27 -- Send logs using ZMQ
28 local LOG = require"log".new(
29   require "log.writer.net.zmq".new("tcp://127.0.0.1:5555")
30 )
31 llthread.set_logger(function(msg) LOG.error(msg) end)
32 -- This error with traceback will be passed to logger
33 error("SOME ERROR")
34 ```
35
36 ### Start atached thread collectd in child thread
37 ``` Lua 
38 -- This is main thread.
39 local thread = require "llthreads".new[[
40   require "utils".sleep(5)
41 ]]
42
43 -- We tell that we start atached thread but child Lua State shuld be close in child thread. 
44 -- So thread:join() can not return any Lua values.
45 -- If `thread` became garbage in main thread then finallizer calls thread:join() 
46 -- and main thread may hungup.
47 thread:start(false, false)
48
49 -- we can call join
50 thread:join()
51 ```
52
53 ### Start detached thread on which we can call join
54 ``` Lua 
55 -- This is main thread.
56 local thread = require "llthreads".new[[
57   require "utils".sleep(5)
58 ]]
59
60 -- We tell that we start detached thread but with ability call thread:join() and 
61 -- gets lua return values from child thread. In fact we start atached thread but if `thread` 
62 -- became garbage in main thread then finallizer just detach child thread and main thread
63 -- may not hungup.
64 thread:start(true, true)
65
66 -- we can call join
67 thread:join()
68 ```
69
70 ### Pass to child thread host application`s library loader
71 If you close parent Lua state then some dynamic library may be unloaded
72 and cfunction in child Lua state (thread) became invalid.
73
74 ``` Lua 
75 -- `myhost.XXX` modules is built-in modules in host application
76 -- host application registers cfunction as module loader
77 local preload = {}
78 preload[ 'myhost.logger' ] = package.preload[ 'myhost.logger' ]
79 preload[ 'myhost.config' ] = package.preload[ 'myhost.config' ]
80 llthreads.new([[
81   -- registers preload
82   local preload  = ...
83   for name, fn in pairs(preload) do package.preload[name] = fn end
84
85   local log = require 'myhost.logger'
86
87 ]], preload):start(true)
88 ```
89
90 [![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/moteus/lua-llthreads2/trend.png)](https://bitdeli.com/free "Bitdeli Badge")
91