Module copas-async
Copas-friendly true asynchronous threads, powered by Lua Lanes.
When loaded this module will initialize LuaLanes by calling
lanes.configure()
without arguments. If you don't want/need that, then
call lanes.configure
before loading/requiring this module.
Usage:
local async = require "copas.async" local function sometask() -- do something that takes a while return ok, err end local ok, err = async(sometask)
Info:
- Copyright: Copyright (c) 2016 Hisham Muhammad, 2022-2023 Thijs Schreijer
- License: MIT, see LICENSE.md.
- Author: Hisham Muhammad
Class future
future:get () | Waits until the async thread finishes (without locking other Copas coroutines) and obtains the result values of the async thread function. |
future:try () | Obtains the result value of the async thread function if it is already available,
or returns false if it is still running. |
Async module
async.addthread (fn) | Runs a function in its own thread, and returns a future. |
async.io_popen (command[, mode="r"]) | Convenience function that runs io.popen(command, mode) in its own async thread. |
async.os_execute (command) | Convenience function that runs an os command in its own async thread. |
async.run (fn) | Runs a function in its own thread, and waits for the results. |
Class future
- future:get ()
-
Waits until the async thread finishes (without locking other Copas coroutines) and
obtains the result values of the async thread function.
Calling on the future object is a shortcut to this get method.
Returns:
-
... the async function results
Usage:
local msg = "hello" copas(function() -- schedule a thread using LuaLanes local future = async.addthread(function() os.execute("for i in seq 5; do echo 'thread says "..msg.." '$i; sleep 1; done") return 123 end) -- The following will wait for the thread to complete (5 secs) -- Note: calling
future()
is the same asfuture:get()
assert(123 == future(), "expected exit code 123") end) - future:try ()
-
Obtains the result value of the async thread function if it is already available,
or returns
false
if it is still running. This function always returns immediately.Returns:
true + ...
(the async function results) when complete, orfalse
if not yet availableUsage:
local msg = "hello" copas(function() -- schedule a thread using LuaLanes local future = async.addthread(function() os.execute("for i in seq 5; do echo 'thread says "..msg.." '$i; sleep 1; done") return 123 end) -- loop to wait for result local done, result while not done do copas.sleep(0.1) done, result = future:try() end assert(123 == future(), "expected exit code 123") end)
Async module
- async.addthread (fn)
-
Runs a function in its own thread, and returns a future.
Note that the function runs it its own Lanes context, so upvalues are copied into the function. When modified in that function, it will not update the original values living Copas side.
Parameters:
- fn function the function to execute async
Returns:
-
a future
- async.io_popen (command[, mode="r"])
-
Convenience function that runs
io.popen(command, mode)
in its own async thread. This allows you to easily run long-lived commands in your own coroutine and get their output (async) without affecting the Copas scheduler as a whole.This function returns (immediately) a descriptor object with an API that matches that of the object returned by io.popen. When commands are issued, this causes the current coroutine to wait until the response is returned, without locking other coroutines (in other words, it uses future internally). Only the methods
fd:read
,fd:write
,fd:close
, andfd:lines
are currently supported.
Note:fd:lines
is not supported on PuC Rio Lua 5.1 (yield across C boundary errors will occur)Parameters:
- command string The command to pass to io.popen in the async thread
- mode string The mode to pass to io.popen in the async thread (default "r")
Returns:
-
descriptor object
- async.os_execute (command)
-
Convenience function that runs an os command in its own async thread.
This allows you to easily run long-lived commands in your own coroutine without
affecting the Copas scheduler as a whole.
This function causes the current coroutine to wait until the command is finished, without locking other coroutines (in other words, it internally runs
get()
in its future).Parameters:
- command string The command to pass to os.execute in the async thread
Returns:
-
the same as os.execute (can differ by platform and Lua version)
- async.run (fn)
-
Runs a function in its own thread, and waits for the results.
This will block the current thread, but will not block other Copas threads.
Parameters:
- fn function the function to execute async
Returns:
-
the original functions return values
Usage:
-- assuming a function returning a value or nil+error, normally called like this; -- -- local result, err = fn() -- -- Can be called non-blocking like this: local result, err = async.run(fn) -- or even shorter; local result, err = async(fn)