Skip to main content

Future

A future represents an asynchronous computation.

A future is a value that might not have finished computing yet. This kind of “asynchronous value” makes it possible for a thread to continue doing useful work while it waits for the value to become available.

The Future:poll Method

The core method of future, poll, attempts to resolve the future into a final value. This method does not block if the value is not ready. Instead, the current task is executed in the background, and its progress is reported when polled. When using a future, you generally won’t call poll directly, but instead Future:await the value. 

local net = require("@lune/net")

local fut: Future<Result<string, string>> = Future.try(function(url)
	local resp = net.request({
		url = url,
		method = "GET",
	})

	assert(resp.ok)

	return resp.body
end, { "https://jsonplaceholder.typicode.com/posts/1" })

local resp: Result<string, string> = fut:await()
print(net.jsonDecode(resp:unwrap()))

Functions​

new​

</>
Future.new(
fn: (...any) → T,--

The function to be executed asynchronously

args: {any}--

The arguments table to be passed to to the function

) → Future<T>--

The constructed future

Constructs a Future from a function to be run asynchronously.

caution

If a the provided function has the possibility to throw an error, instead of any other rusty-luau types like Result or Option, use Future:try instead.

try​

</>
Future.try(
fn: (...any) → T,--

The fallible function to be executed asynchronously

args: {any}--

The arguments table to be passed to to the function

) → Future<Result<T>>--

The constructed future

Constructs a fallible Future from a function to be run asynchronously.

poll​

</>
Future.poll(self: Future<T>) → (
Status,
Option<T>
)--

Returns the Status and an optional return if completed

Polls a Future to completion.

cancel​

</>
Future.cancel(self: Future<T>) → ()

Cancels a Future.

await​

</>
Future.await(self: Future<T>) → T--

The value returned by the function on completion

Suspend execution until the result of a Future is ready. This method continuosly polls a Future until it reaches completion.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a [Future] from a function to be run asynchronously. \n\n:::caution\nIf a the provided function has the possibility to throw an error, instead of any \nother rusty-luau types like [Result] or [Option], use [Future:try] instead.\n:::",
            "params": [
                {
                    "name": "fn",
                    "desc": "The function to be executed asynchronously",
                    "lua_type": "(...any) -> T"
                },
                {
                    "name": "args",
                    "desc": "The arguments table to be passed to to the function",
                    "lua_type": "{ any }"
                }
            ],
            "returns": [
                {
                    "desc": "The constructed future",
                    "lua_type": "Future<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 112,
                "path": "lib/future.luau"
            }
        },
        {
            "name": "try",
            "desc": "Constructs a fallible [Future] from a function to be run asynchronously. ",
            "params": [
                {
                    "name": "fn",
                    "desc": "The fallible function to be executed asynchronously",
                    "lua_type": "(...any) -> T"
                },
                {
                    "name": "args",
                    "desc": "The arguments table to be passed to to the function",
                    "lua_type": "{ any }"
                }
            ],
            "returns": [
                {
                    "desc": "The constructed future",
                    "lua_type": "Future<Result<T>>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 130,
                "path": "lib/future.luau"
            }
        },
        {
            "name": "poll",
            "desc": "Polls a [Future] to completion. ",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Future<T>"
                }
            ],
            "returns": [
                {
                    "desc": "Returns the [Status] and an optional return if completed",
                    "lua_type": "(Status, Option<T>)"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 148,
                "path": "lib/future.luau"
            }
        },
        {
            "name": "cancel",
            "desc": "Cancels a [Future]. ",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Future<T>"
                }
            ],
            "returns": [],
            "function_type": "static",
            "source": {
                "line": 185,
                "path": "lib/future.luau"
            }
        },
        {
            "name": "await",
            "desc": "Suspend execution until the result of a [Future] is ready. \nThis method continuosly polls a [Future] until it reaches completion. ",
            "params": [
                {
                    "name": "self",
                    "desc": "",
                    "lua_type": "Future<T>"
                }
            ],
            "returns": [
                {
                    "desc": "The value returned by the function on completion",
                    "lua_type": "T"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 199,
                "path": "lib/future.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "Status",
            "desc": "Represents the status of a [Future].",
            "lua_type": "\"initialized\" | \"pending\" | \"cancelled\" | \"ready\"",
            "private": true,
            "source": {
                "line": 59,
                "path": "lib/future.luau"
            }
        },
        {
            "name": "Future<T>",
            "desc": "Represents the internal state of a [Future].",
            "fields": [
                {
                    "name": "_thread",
                    "lua_type": "thread",
                    "desc": "The background coroutine spawned for execution"
                },
                {
                    "name": "_ret",
                    "lua_type": "T",
                    "desc": "The value returned once execution has halted"
                },
                {
                    "name": "_spawnEvt",
                    "lua_type": "Signal<()>",
                    "desc": "Event for internal communication among threads pre execution"
                },
                {
                    "name": "_retEvt",
                    "lua_type": "Signal<T | Result<T, string>, Status>",
                    "desc": "Event for internal communication among threads post execution"
                },
                {
                    "name": "_status",
                    "lua_type": "Status",
                    "desc": "The status of the Future"
                }
            ],
            "private": true,
            "source": {
                "line": 75,
                "path": "lib/future.luau"
            }
        }
    ],
    "name": "Future",
    "desc": "A future represents an asynchronous computation.\n\nA future is a value that might not have finished computing yet. This kind of “asynchronous value” \nmakes it possible for a thread to  continue doing useful work while it waits for the value to \nbecome available.\n\n### The [Future:poll] Method\nThe core method of future, poll, attempts to resolve the future into a final value. This method does \nnot block if the value is not ready. Instead, the current task is executed in the background, and\nits progress is reported when polled. When using a future, you generally won’t call poll directly, \nbut instead [Future:await] the value.\n\n```lua\nlocal net = require(\"@lune/net\")\n\nlocal fut: Future<Result<string, string>> = Future.try(function(url)\n\tlocal resp = net.request({\n\t\turl = url,\n\t\tmethod = \"GET\",\n\t})\n\n\tassert(resp.ok)\n\n\treturn resp.body\nend, { \"https://jsonplaceholder.typicode.com/posts/1\" })\n\nlocal resp: Result<string, string> = fut:await()\nprint(net.jsonDecode(resp:unwrap()))\n```",
    "source": {
        "line": 50,
        "path": "lib/future.luau"
    }
}