Merge pull request #27 from loud-hound/iudalov/docs

README.md updates & scetch of docs

CMakeLists.txt

@@ -23,7 +23,7 @@ target_link_libraries(effil -lpthread ${LUA_LIBRARY})
 
 set(GENERAL "-std=c++14 -pthread")
 set(ENABLE_WARNINGS "-Wall -Wextra -pedantic -Werror")
-set(BUILD_FLAVOR "-O3 -UNDEBUG")
+set(BUILD_FLAVOR "-O3 -DNDEBUG")
 set_target_properties(effil PROPERTIES COMPILE_FLAGS "${ENABLE_WARNINGS} ${GENERAL} ${BUILD_FLAVOR}")
 
 #----------

README.md

@@ -1,5 +1,81 @@
 # Effil
-Threading library for Lua. Written in C++ with great help of [sol2](https://github.com/ThePhD/sol2).
+Lua library for real multithreading. Written in C++ with great help of [sol2](https://github.com/ThePhD/sol2).
 
 [![Build Status](https://travis-ci.org/loud-hound/effil.svg?branch=master)](https://travis-ci.org/loud-hound/effil)
 [![Documentation Status](https://readthedocs.org/projects/effil/badge/?version=latest)](http://effil.readthedocs.io/en/latest/?badge=latest)
+
+## How to install
+### Build from src on Linux and Mac
+1. `git clone git@github.com:loud-hound/effil.git effil && cd effil`
+2. `mkdir build && cd build && make -j4 `
+3. Add libeffil.so or libeffil.dylib to your lua `package.path`.
+
+### From lua rocks
+Coming soon.
+
+## Quick guide for impatient
+As you may now there are not much script
+languages with **real** multithreading support
+(Lua/Python/Ruby and etc has global interpreter lock aka GIL).
+Effil solves this problem by running independent Lua VM
+in separate native thread and provides robust communicating primitives
+for creating threads (VM instances) and data sharing.
+
+Effil library provides two major functions:
+1. `effil.thread(action)` - function which creates threads.
+2. `effil.table` - table that persist in all threads and behaves just like regular lua table.
+3. Bunch og utilities to handle threads and tables.
+
+## Examples
+### Spawn the thread
+```lua
+local effil = require("libeffil")
+function bark(name)
+    print(name .. ": bark")
+end
+
+-- associate bark with thread
+-- invoke bark in separate thread with spark argument
+-- wait while Sparky barks
+effil.thread(bark)("Sparky"):wait()
+```
+Output: `Sparky: bark`
+### Sharing data
+```lua
+
+local effil = require("libeffil")
+
+function download_heavy_file(url, files)
+    -- i am to lazy to write real downloading here
+    files[url] = "content of " .. url
+end
+
+-- shared table for data exchanging
+local files = effil.table {}
+local urls = {"luarocks.org", "ya.ru", "github.com"}
+local downloads = {}
+-- capture function for further threads
+local downloader = effil.thread(download_heavy_file)
+
+for i, url in pairs(urls) do
+    -- run downloads in separate threads
+    -- each invocation creates separate thread
+    downloads[url] = downloader(url, files)
+end
+
+for i, url in pairs(urls) do
+    -- here we go
+    downloads[url]:wait()
+    print("Downloaded: "  .. files[url])
+end
+
+```
+Output:
+```
+Downloaded:File contentluarocks.org
+Downloaded:File contentya.ru
+Downloaded:File contentgithub.com
+```
+
+## Reference
+There is no

src/cpp/lua-module.cpp

@@ -12,7 +12,7 @@ sol::object createThreadFactory(sol::this_state lua, const sol::function& func)
     return sol::make_object(lua, std::make_unique<ThreadFactory>(func));
 }
 
-sol::object createShare(sol::this_state lua) { return sol::make_object(lua, getGC().create<SharedTable>()); }
+sol::object createTable(sol::this_state lua) { return sol::make_object(lua, getGC().create<SharedTable>()); }
 
 } // namespace
 
@@ -25,7 +25,7 @@ extern "C" int luaopen_libeffil(lua_State* L) {
                                                   "thread_id", threadId,         //
                                                   "sleep", sleep,                //
                                                   "yield", yield,                //
-                                                  "share", createShare           //
+                                                  "table", createTable           //
                                                   );
     sol::stack::push(lua, public_api);
     return 1;

tests/lua/smoke_test.lua

@@ -7,7 +7,7 @@ end
 
 function TestSmoke:testSharedTableTypes()
     local effil = require('libeffil')
-    local share = effil.share()
+    local share = effil.table()
 
     share["number"] = 100500
     share["string"] = "string value"
@@ -51,7 +51,7 @@ end
 
 function TestSmoke:testThreadPauseAndResume()
     local effil = require('libeffil')
-    local data = effil.share()
+    local data = effil.table()
     data.value = 0
     local thread_runner = effil.thread(
         function(data)
@@ -79,7 +79,7 @@ end
 function TestSmoke:testThreadPauseAndStop()
     local effil = require('libeffil')
     log "Create thread"
-    local data = effil.share()
+    local data = effil.table()
     data.value = 0
     local thread_runner = effil.thread(
         function(data)
@@ -106,7 +106,7 @@ end
 function TestSmoke:testThreadPauseAndStop()
     local effil = require('libeffil')
     log "Create thread"
-    local data = effil.share()
+    local data = effil.table()
     data.value = 0
     local thread_runner = effil.thread(
         function(data)
@@ -132,11 +132,11 @@ end
 
 function TestSmoke:testRecursiveTables()
     local effil = require('libeffil')
-    local share = effil.share()
+    local share = effil.table()
 
     local magic_number = 42
-    share["subtable1"] = effil.share()
-    share["subtable1"]["subtable1"] = effil.share()
+    share["subtable1"] = effil.table()
+    share["subtable1"]["subtable1"] = effil.table()
     share["subtable1"]["subtable2"] = share["subtable1"]["subtable1"]
     share["subtable2"] = share["subtable1"]["subtable1"]
     share["magic_number"] = magic_number
@@ -159,7 +159,7 @@ end
 
 function TestSmoke:testThisThreadFunctions()
     local effil = require('libeffil')
-    local share = effil.share()
+    local share = effil.table()
 
     local thread_factory = effil.thread(
         function(share)
@@ -188,7 +188,7 @@ end
 
 function TestSmoke:testCheckThreadReturns()
     local effil = require('libeffil')
-    local share = effil.share()
+    local share = effil.table()
     share.value = "some value"
 
     local thread_factory = effil.thread(
@@ -220,7 +220,7 @@ end
 
 function TestSmoke:testCheckPairsInterating()
     local effil = require('libeffil')
-    local share = effil.share()
+    local share = effil.table()
     local data = { 0, 0, 0, ["key1"] = 0, ["key2"] = 0, ["key3"] = 0 }
 
     for k, _ in pairs(data) do
@@ -252,7 +252,7 @@ end
 
 function TestSmoke:testCheckLengthOperator()
     local effil = require('libeffil')
-    local share = effil.share()
+    local share = effil.table()
     share[1] = 10
     share[2] = 20
     share[3] = 30