Future

static deferred<infer Value>(_ compute: () -> Value) -> Future<Value>

Answers a Future that runs the given Function when it is started.

Nothing runs while the Future is being built. Each start calls the Function again, so two starts answer two values, and a Function reading something that changes reads it at each start.

The Function runs on the Program's own thread, from beginning to end, with nothing else in between. It is the way to describe a computation as work rather than to carry one out somewhere else.

Returns a Future answering what the computation answers.

variable starts = 0

constant counted = Async.deferred(() {
	starts = starts::add(1)

	<- starts
})

expect starts::is(0)

constant first = complete counted
constant second = complete counted

expect first::is(1)
expect second::is(2)

static sleep(milliseconds duration: Integer) -> Future<{}>

Answers a Future that waits the given number of milliseconds.

Nothing waits while the Future is being built. Each start waits again, so a Future that is started twice waits twice.

A wait that is stopped never answers. The runs that within and race leave behind are stopped, and what one would have answered is never read.

Returns a Future answering nothing, once the time has passed.

map<infer Other>(_ transform: (_: Value) -> Other) -> Future<Other>

Answers a Future that runs this one and hands its value to the transform.

Nothing runs while the answer is being built. Each start of the answer starts the receiver again, so two starts run the work twice and call the transform twice.

Returns a Future answering what the transform answers.

constant price = Async.deferred(() { <- 40 })
constant total = complete price::map((amount) { <- amount::add(2) })

expect total::is(42)

map<infer Other>(_ transform: (_: Value) -> Other) -> Started<Other>

Answers the same run, with its value handed to the transform.

The work is in flight already and nothing here starts it again, so the transform runs once however often the answer is completed.

Returns the run, answering what the transform answers.

constant run = start Async.deferred(() { <- 20 })
constant doubled = complete run::map((n) { <- n::multiply(with 2) })

expect doubled::is(40)

andThen<infer Other>(
	_ next: (_: Value) -> Future<Other>,
) -> Future<Other>

Answers a Future that runs this one, and then the one the next Function builds from its value.

The Function is called once the receiver has answered, so what it builds can read that value. Nothing runs while the answer is being built.

Returns a Future answering what the next work answers.

constant userId = Async.deferred(() { <- 7 })
constant greeting = complete userId::andThen((id) {
	<- Async.deferred(() { <- "Hello, user {id}" })
})

expect greeting::is("Hello, user 7")

andThen<infer Other>(_ next: Future<Other>) -> Future<Other>

Answers a Future that runs this one, and then the given one.

The value the receiver answers with is dropped. This is the entry for work run for its effect, where what comes next does not read it.

Returns a Future answering what the given work answers.

constant save = Async.deferred(() { <- "saved" })
constant notify = Async.deferred(() { <- "notified" })
constant answer = complete save::andThen(notify)

expect answer::is("notified")

within(milliseconds limit: Integer) -> Future<Optional<Value>>

Answers a Future that runs this one, and answers nothing where it takes too long.

The run is stopped at the deadline. It was started by this Method and nothing else can be waiting for it, so what it would have answered is never read.

The answer is an Optional rather than a failure, because a deadline is a question the caller asked rather than something that went wrong.

Returns the value, or nothing where the deadline passed first.

constant quick = Async.deferred(() { <- "ready" })
constant answer = complete quick::within(milliseconds 1000)

expect answer::is("ready")

within(milliseconds limit: Integer) -> Started<Optional<Value>>

Answers the same run, giving up on it after the given number of milliseconds.

The run is not stopped. A Started can be completed from anywhere, so a deadline one holder writes can not stop the work another is waiting for. The waiting stops and the work goes on.

A host with an event loop stays open until that work is over. Giving up on an answer is not giving up on the run, so a Program can not exit ahead of it.

The time is counted from here, because the run is in flight already.

Returns the value, or nothing where the deadline passed first.

constant run = start Async.deferred(() { <- "ready" })
constant answer = complete run::within(milliseconds 1000)

expect answer::is("ready")

attempt(times count: Integer) -> Future<Result<Value, Failure>>

Answers a Future that runs this one until it answers a value, up to the given number of attempts.

The first attempt is one of the count, so attempt(times 3) runs the work three times at worst. A count below two is one attempt.

The answer is the first value, or the last reason where every attempt failed.

Returns a Future answering the first value, or the last reason.

variable calls = 0

constant flaky = Async.deferred(() -> Result<Integer, String> {
	calls = calls::add(1)

	if calls::isLessThan(3) {
		<- #Failure("busy on call {calls}")
	}

	<- #Value(calls)
})

constant gaveUp = complete flaky::attempt(times 2)
constant answered = complete flaky::attempt(times 5)

expect gaveUp::is(#Failure("busy on call 2"))
expect answered::is(3)

attempt(
	times count: Integer,
	pausingMilliseconds pause: Integer,
) -> Future<Result<Value, Failure>>

Answers the same, waiting the given number of milliseconds between two attempts.

The wait is between attempts, and never before the first or after the last.

Returns a Future answering the first value, or the last reason.

constant ready = Async.deferred(() -> Result<String, String> {
	<- #Value("saved")
})

constant answer = complete ready::attempt(
	times 3,
	pausingMilliseconds 200,
)

expect answer::is("saved")

inSequence() -> Future<List<Value>>

Answers a Future running every one of them in order, each started once the one before it has answered.

The answer holds one value per item, in the receiver's order. The empty List answers the empty List.

This is the entry for work that is not independent. A host can refuse a second request at once, and a walk can have an order that is what the answer means.

Returns a Future answering the List of values.

constant steps = [
	Async.deferred(() { <- "fetch" }),
	Async.deferred(() { <- "parse" }),
]
constant none: List<Future<String>> = []

constant done = complete steps::inSequence()
constant nothing = complete none::inSequence()

expect done::is(["fetch", "parse"])
expect nothing::isEmpty()

all() -> Future<List<Value>>

Answers a Future starting every one of them at once, and answering their values in the receiver's order.

The order of the answer is the receiver's, whatever order the runs finish in. The empty List answers the empty List.

Everything runs on the Program's own thread, so what this saves is the waiting rather than the computing.

Returns a Future answering the List of values.

constant lookups = [
	Async.deferred(() { <- "Ada" }),
	Async.deferred(() { <- "Grace" }),
]
constant names = complete lookups::all()

expect names::is(["Ada", "Grace"])

all(atMost count: Integer) -> Future<List<Value>>

Answers the same, with at most the given number of runs in flight at once.

A count below one runs them one at a time, and a count above the length runs them all at once.

Returns a Future answering the List of values.

constant pages = [
	Async.deferred(() { <- 1 }),
	Async.deferred(() { <- 2 }),
	Async.deferred(() { <- 3 }),
]
constant numbers = complete pages::all(atMost 2)

expect numbers::is([1, 2, 3])

race() -> Future<Value>

Answers a Future starting every one of them at once, and answering with the first value any of them answers.

Every other run is stopped as soon as one has answered. What a stopped run would have answered is never read.

Returns a Future answering the first value.

constant quick = Async.deferred(() { <- "quick" })
constant slow = Async.sleep(milliseconds 60000)::map((_) {
	<- "slow"
})

constant first = complete [slow, quick]::race()

expect first::is("quick")

firstValue() -> Future<Optional<Value>>

Answers a Future starting every one of them at once, and answering with the value of the first that answers one.

A run that fails is not an answer, and the waiting goes on. Every other run is stopped as soon as one has answered a value.

A List whose every run failed answers nothing, and so does the empty List. The name is OptionalList::firstValue's, for the same question one level along.

Returns the first value, or nothing where every run failed.

constant down: Result<String, String> = #Failure("down")
constant up: Result<String, String> = #Value("mirror")

constant mirrors = [
	Async.deferred(() { <- down }),
	Async.deferred(() { <- up }),
]
constant failing = [Async.deferred(() { <- down })]

constant found = complete mirrors::firstValue()
constant missing = complete failing::firstValue()

expect found::is("mirror")
expect missing::isEmpty()