copas-async

Contents

• Class future
• Async module

Modules

• copas-async

Topics

• 1. Introduction
• CHANGELOG
• MIT License

Examples

• example-popen.lua
• example.lua

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

Async module

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 as future: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, or false if not yet available

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)

   -- 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, and fd: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)