Represents the state of an asynchronous action that will be completed some time in the future.

In rtk, asynchronous tasks, such as animations, will return an rtk.Future where you have the opportunity to register callbacks to optionally perform subsequent actions (after()), or callbacks to be invoked when the Future is fully resolved (done()).

If the asynchronous task supports it, it can also be cancelled (cancel()).

Example

-- Kick off an animation sequence.  rtk.Widget:animate() returns an rtk.Future.
widget:animate{'bg', dst='red'}
   :after(function()
       -- Once the background color animates to red, now animate it to
       -- turquoise with a different easing.
       return widget:animate{'bg', dst='turquoise', easing='in-out-elastic'}
   end)
   :after(function()
       -- And now once the animation to turquoise completes, animate the
       -- width to 60% of the widget's parent's width.
       return widget:animate{'w', dst=0.6}
   end)
   :done(function()
       -- Finally all 'after' callbacks have completed.
       log.info('animation sequence complete')
   end)
   :cancelled(function()
       -- If cancel() was called on the Future then we'll log this message.
       log.warning('animation sequence was cancelled')
   end)

Used with the state attribute.

Attributes

rtk.Future.state futurestateconst read-only ¶

Represents the current state of the Future.

rtk.Future.result any read-only ¶

The result returned by the asynchronous task as passed to either resolve() or cancel().

rtk.Future.cancellable boolean read-only ¶

If true, the owner of the asynchronous task has registered a cancelled callback to cancel the operation, which allows cancel() to be called.

Methods

rtk.Future() ¶

Create a new Future object.

Return Values

(rtk.Future)

the new Future object

rtk.Future:after(func) ¶

Register a callback to be invoked after the current task completes, but before done callbacks are invoked.

Multiple callbacks can be registered and will be invoked in the order they were added.

If the callback returns another rtk.Future then that Future is chained to this one, such that the new Future must complete before any subsequent after callbacks registered against this Future will be invoked (and likewise for done). If a dependent Future is in-flight and this one is cancelled, then the dependent Future will also be cancelled. The reverse is not true, however: if a dependent Future is cancelled,

If the rtk.Future has already been resolved before registering func, it will still be executed at the beginning of the next {rtk.Window.onupdate|update cycle}.

Parameters

func

(function)

the function that's invoked after the asynchronous task completes, and which receives as an argument the return value from the asynchronous task if it's the first after callback, or the return value of the previously invoked after callback. If no value is returned by the callback, then the previous non-nil return value in the chain will be passed.

Return Values

(rtk.Future)

returns self for method chaining

rtk.Future:done(func) ¶

Register a callback to be invoked when the Future completes (not cancelled) and after all after() callbacks have been invoked.

Multiple callbacks can be registered and will be invoked in the order they were added.

If the rtk.Future has already been resolved before registering func, it will still be executed at the beginning of the next {rtk.Window.onupdate|update cycle}.

Parameters

func

(function)

the function that's invoked after the asynchronous task completes and all after callbacks. This callback receives as an argument the last non-nil value returned by the original asynchronous task or by any after() callbacks.

Return Values

(rtk.Future)

returns self for method chaining

rtk.Future:cancelled(func) ¶

Register a callback to be invoked when the Future is cancelled.

Multiple callbacks can be registered and will be invoked in the order they were added.

If the rtk.Future has already been cancelled before registering func, then it will be immediately invoked.

Parameters

func

(function)

the function that's invoked when cancel() is called, and which receives as an argument the value passed to cancel().

Return Values

(rtk.Future)

returns self for method chaining

rtk.Future:cancel(v) ¶

Cancels the Future and invokes all previously registered cancelled callbacks.

The cancelled callbacks are immediately invoked in order.

It is a runtime error to cancel() an rtk.Future that has no cancelled callbacks. You can check the cancellable attribute first to determine if the Future can be cancelled.

Parameters

v

(any)

the arbitrary value to be passed to the registered cancelled callbacks.

Return Values

(rtk.Future)

returns self for method chaining

rtk.Future:resolve(value) ¶

Resolves the Future, causing all after and done callbacks to be invoked.

Usually this method will only be called by the originator of the asynchronous task.

If there have been any after or done callbacks registered, they are immediately invoked. But if no callbacks have been attached, then they will be rechecked after one {rtk.Window.onupdate|update cycle}, allowing the opportunity for callbacks to be registered even after the rtk.Future is resolved.

The Future may not transition to the DONE state after calling this method: if any after callbacks return a Future, they will be chained, and this Future will not transition to DONE until all dependent Futures also complete.

Parameters

value

(any)

the arbitrary value returned by the asynchronous task, and that will be passed into the after and done callbacks (unless any after callback returns a different non-nil value, in which case that takes precedence).

Return Values

(rtk.Future)

returns self for method chaining