Async

Unstable Doc Ahead

The following documentation is lacking in detail. Be sure to check back for updates, or jump in if you can add any addtional information.

Using an async process, you can run longer-term child processes within the client lifecycle, without blocking the main loop. An async object holds the client request (and connection) until the subprocess has finished.

`cloud.async`

Using Async

An async object needs a child process to run. This is represented by a function that gets passed to the async.start method. You can also pass additional arguments to the async.start as well.

It's generally a good idea to create an "enclosure", and pass that to the async object. This allows you to use items from the outer scope in the child process.

Example

-- child process
local mathRan = math.random
local child_proc = function()
  cloud.log(mathRan(100))
end

local async, err = cloud.async.start(child_proc)

...

Another way to pass resources is through the async.start arguments.

Example

-- child process
local child_proc = function(mathRan, log)
  log(mathRan(100))
end
local async, err = cloud.async.start(child_proc, math.random, cloud.log)

Did You Know?

It's generally a better practice to use enclosures when possible.

Start

.start

Creates and starts a new async process.

Signature

cloud.async.start(child_func[, arg[, ...]])

Parameters

Name	Description	Type	Default	Required
`child_func`	The child process to run.	function	`nil`	Y
`arg`	Arguments, comma delimited to be passed to the child function.	string	`nil`	N

Returns

An async object, or nil and an error message. The returned async object can be used with both async.wait and async.stop.

Example

-- Create child process
local child = function()
  cloud.log('did something')
  return
end

local async, err = cloud.async.start(child)
if not async then
  cloud.log(err)
end

return async

Stop

.stop

Stops a previously started async process.

Signature

cloud.async.stop( async_obj )

Parameters

Name	Description	Type	Default	Required
`async_obj`	The `async` object returned from `async.start`.	userdata	`nil`	Y

Returns

A success boolean, or nil and an error message.

Example

local success, err = cloud.async.stop( async_id )
if not success then
  cloud.log(err)
end

Wait

.wait

Waits for multiple async processes to finish.

Signature

cloud.async.wait( asyncs )

Parameters

Name	Description	Type	Default	Required
`asyncs`	A table array of `async` objects.	table	`nil`	Y

Returns

A result table array, or nil and an error message.

Example

-- Mixing enclosure and arguments

local math_random = math.random

local child_proc = function(log)
  log(math_random(100))
end

local a1, err1 = cloud.async.start(child_proc, cloud.log)
local a2, err2 = cloud.async.start(child_proc, cloud.log)

local asyncs = { a1, a2 }

local results, err = cloud.async.wait( asyncs )
if not results then
  cloud.log(err)
  return
end

return results