From 7ac6014329869862179a7d093fdb39480b496e09 Mon Sep 17 00:00:00 2001 From: Ilia Udalov Date: Sun, 5 Mar 2017 02:27:11 +0300 Subject: [PATCH 1/2] README.md updates & scetch of docs --- CMakeLists.txt | 2 +- README.md | 78 +++++++++++++++++++++++++++++++++++++++++- src/cpp/lua-module.cpp | 4 +-- 3 files changed, 80 insertions(+), 4 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 304ce41..83867a2 100644 --- a/CMakeLists.txt +++ b/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}") #---------- diff --git a/README.md b/README.md index 37a3a5f..8617725 100644 --- a/README.md +++ b/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 \ No newline at end of file diff --git a/src/cpp/lua-module.cpp b/src/cpp/lua-module.cpp index 2ba9b01..c31e560 100644 --- a/src/cpp/lua-module.cpp +++ b/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(func)); } -sol::object createShare(sol::this_state lua) { return sol::make_object(lua, getGC().create()); } +sol::object createTable(sol::this_state lua) { return sol::make_object(lua, getGC().create()); } } // 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; From 53a6d812a1bfe4790a74aa4b50f39501adcf20d9 Mon Sep 17 00:00:00 2001 From: Ilia Udalov Date: Sun, 5 Mar 2017 02:34:28 +0300 Subject: [PATCH 2/2] Fix naming --- tests/lua/smoke_test.lua | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/tests/lua/smoke_test.lua b/tests/lua/smoke_test.lua index c08c26d..e5fa507 100644 --- a/tests/lua/smoke_test.lua +++ b/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