§tiro::resumable_frame

Represents the call frame of a resumable function call. More...

#include "tiropp/functions.hpp"

§Public Types

§Public Functions

§Detailed Description

class tiro::resumable_frame;

Represents the call frame of a resumable function call.

References to an instance of this class are only valid from within the native function implementing the resumable function call.

§Public Types Documentation

§enum frame_state

Lists well known state values used by resumable functions.

All positive integers can be used freely by the application.

§Public Functions Documentation

§function resumable_frame

inline resumable_frame(
    tiro_vm_t raw_vm,
    tiro_resumable_frame_t raw_frame
)

§function resumable_frame

resumable_frame(
    const resumable_frame & 
) =delete

§function operator=

resumable_frame & operator=(
    const resumable_frame & 
) =delete

§function arg_count

inline size_t arg_count() const

Returns the number of arguments passed to this function call.

§function arg

inline handle arg(
    size_t index
) const

Returns the argument at the given index (0 <= index < argc).

§function closure

inline handle closure() const

Returns the closure value referenced by this function (if any).

§function local_count

inline size_t local_count() const

Returns the number of local values available to the function frame.

§function local

inline handle local(
    size_t index
) const

Returns the current value of the local slot with the given index.

§function set_local

inline void set_local(
    size_t index,
    const handle & value
)

Sets the current value of the local slot with the given index to value.

§function state

inline int state() const

Returns the current state of this frame.

§function set_state

inline void set_state(
    int next_state
)

Sets the current state of this frame.

Parameters:

• next_state The new state value

It is usually not necessary to invoke this function directly as changing the state is also implied by other methods like [invoke()](/docs/api/classes/classtiro_1_1resumable__frame#function-invoke) and [return_value()](/docs/api/classes/classtiro_1_1resumable__frame#function-return-value).

The calling native function should return after altering the state. The new state will be active when the native function is called for the next time.

Note that a few states have special meaning (see resumable_frame_state).

§function invoke

inline void invoke(
    int next_state,
    const function & func,
    const tuple & args
)

Signals the vm that the function func shall be invoked with the given arguments in args.

Parameters:

• next_state The new state value
• func The target function to invoke
• args The call arguments

func will be invoked after the native function returned to the vm. The current native function will be called again when func has itself returned, and its return value will be accessible via [invoke_return()](/docs/api/classes/classtiro_1_1resumable__frame#function-invoke-return).

Calling this function implies a state change to next_state, which will be the frame's state when the native function is called again after func's execution.

§function invoke

inline void invoke(
    int next_state,
    const function & func
)

Like above, but calls the given function without any arguments.

§function invoke_return

inline handle invoke_return() const

Returns the result of the last function call made via [invoke()](/docs/api/classes/classtiro_1_1resumable__frame#function-invoke).

Only returns a useful value when the native function is called again for the first time after calling [invoke()](/docs/api/classes/classtiro_1_1resumable__frame#function-invoke) and returning to the vm.

§function return_value

inline void return_value(
    const handle & value
)

Sets the return value for the given function call frame to the given value.

The call frame's state is also set to END as a result of this call.

§function panic_msg

inline void panic_msg(
    std::string_view message
)

Signals a panic from the given function call frame.

The call frame's state is also set to END as a result of this call.

TODO: Allow user defined exception objects instead of plain string?

§function raw_vm

inline tiro_vm_t raw_vm() const

§function raw_frame

inline tiro_resumable_frame_t raw_frame() const

Updated on 2022-02-27 at 21:17:13 +0100