'async' Dialect

Types and operations for async dialect

This dialect contains operations for modeling asynchronous execution.

Operations ¶

source

async.add_to_group (async::AddToGroupOp) ¶

Adds and async token or value to the group

Syntax:

operation ::= `async.add_to_group` $operand `,` $group `:` type($operand) attr-dict

The async.add_to_group adds an async token or value to the async group. Returns the rank of the added element in the group. This rank is fixed for the group lifetime.

Example:

%0 = async.create_group %size : !async.group
%1 = ... : !async.token
%2 = async.add_to_group %1, %0 : !async.token

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.await (async::AwaitOp) ¶

Waits for the argument to become ready

Syntax:

operation ::= `async.await` $operand `:` custom<AwaitResultType>(
              type($operand), type($result)
              ) attr-dict

The async.await operation waits until the argument becomes ready, and for the async.value arguments it unwraps the underlying value

Example:

%0 = ... : !async.token
async.await %0 : !async.token

%1 = ... : !async.value<f32>
%2 = async.await %1 : !async.value<f32>

Operands: ¶

Results: ¶

async.await_all (async::AwaitAllOp) ¶

Waits for the all async tokens or values in the group to become ready

Syntax:

operation ::= `async.await_all` $operand attr-dict

The async.await_all operation waits until all the tokens or values in the group become ready.

Example:

%0 = async.create_group %size : !async.group

%1 = ... : !async.token
%2 = async.add_to_group %1, %0 : !async.token

%3 = ... : !async.token
%4 = async.add_to_group %2, %0 : !async.token

async.await_all %0

Operands: ¶

async.call (async::CallOp) ¶

Async call operation

Syntax:

operation ::= `async.call` $callee `(` $operands `)` attr-dict `:` functional-type($operands, results)

The async.call operation represents a direct call to an async function that is within the same symbol scope as the call. The operands and result types of the call must match the specified async function type. The callee is encoded as a symbol reference attribute named “callee”.

Example:

%2 = async.call @my_add(%0, %1) : (f32, f32) -> !async.value<f32>

Interfaces: CallOpInterface, SymbolUserOpInterface

Attributes: ¶

Operands: ¶

Results: ¶

async.coro.begin (async::CoroBeginOp) ¶

Returns a handle to the coroutine

Syntax:

operation ::= `async.coro.begin` $id attr-dict

The async.coro.begin allocates a coroutine frame and returns a handle to the coroutine.

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.coro.end (async::CoroEndOp) ¶

Marks the end of the coroutine in the suspend block

Syntax:

operation ::= `async.coro.end` $handle attr-dict

The async.coro.end marks the point where a coroutine needs to return control back to the caller if it is not an initial invocation of the coroutine. It the start part of the coroutine is is no-op.

Operands: ¶

async.coro.free (async::CoroFreeOp) ¶

Deallocates the coroutine frame

Syntax:

operation ::= `async.coro.free` $id `,` $handle attr-dict

The async.coro.free deallocates the coroutine frame created by the async.coro.begin operation.

Operands: ¶

async.coro.id (async::CoroIdOp) ¶

Returns a switched-resume coroutine identifier

Syntax:

operation ::= `async.coro.id` attr-dict

The async.coro.id returns a switched-resume coroutine identifier.

Interfaces: InferTypeOpInterface

Results: ¶

async.coro.save (async::CoroSaveOp) ¶

Saves the coroutine state

Syntax:

operation ::= `async.coro.save` $handle attr-dict

The async.coro.saves saves the coroutine state.

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.coro.suspend (async::CoroSuspendOp) ¶

Suspends the coroutine

Syntax:

operation ::= `async.coro.suspend` $state `,` $suspendDest `,` $resumeDest  `,` $cleanupDest attr-dict

The async.coro.suspend suspends the coroutine and transfers control to the suspend successor. If suspended coroutine later resumed it will transfer control to the resume successor. If it is destroyed it will transfer control to the the cleanup successor.

In switched-resume lowering coroutine can be already in resumed state when suspend operation is called, in this case control will be transferred to the resume successor skipping the suspend successor.

Traits: Terminator

Operands: ¶

Successors: ¶

async.create_group (async::CreateGroupOp) ¶

Creates an empty async group

Syntax:

operation ::= `async.create_group` $size `:` type($result) attr-dict

The async.create_group allocates an empty async group. Async tokens or values can be added to this group later. The size of the group must be specified at construction time, and await_all operation will first wait until the number of added tokens or values reaches the group size.

Example:

%size = ... : index
%group = async.create_group %size : !async.group
...
async.await_all %group

Traits: AlwaysSpeculatableImplTrait

Interfaces: ConditionallySpeculatable, InferTypeOpInterface, NoMemoryEffect (MemoryEffectOpInterface)

Effects: MemoryEffects::Effect{}

Operands: ¶

Results: ¶

async.execute (async::ExecuteOp) ¶

Asynchronous execute operation

The body region attached to the async.execute operation semantically can be executed concurrently with the successor operation. In the followup example “compute0” can be executed concurrently with “compute1”.

The actual concurrency semantics depends on the dialect lowering to the executable format. Fully sequential execution (“compute0” completes before “compute1” starts) is a completely legal execution.

Because concurrent execution is not guaranteed, it is illegal to create an implicit dependency from “compute1” to “compute0” (e.g. via shared global state). All dependencies must be made explicit with async execute arguments (async.token or async.value).

async.execute operation takes async.token dependencies and async.value operands separately, and starts execution of the attached body region only when all tokens and values become ready.

Example:

%dependency = ... : !async.token
%value = ... : !async.value<f32>

%token, %results =
  async.execute [%dependency](%value as %unwrapped: !async.value<f32>)
             -> !async.value<!some.type>
  {
    %0 = "compute0"(%unwrapped): (f32) -> !some.type
    async.yield %0 : !some.type
  }

%1 = "compute1"(...) : !some.type

In the example above asynchronous execution starts only after dependency token and value argument become ready. Unwrapped value passed to the attached body region as an %unwrapped value of f32 type.

Traits: AttrSizedOperandSegments, AutomaticAllocationScope, SingleBlockImplicitTerminator<YieldOp>, SingleBlock

Interfaces: RegionBranchOpInterface

Operands: ¶

Results: ¶

async.func (async::FuncOp) ¶

Async function operation

An async function is like a normal function, but supports non-blocking await. Internally, async function is lowered to the LLVM coroutinue with async runtime intrinsic. It can return an async token and/or async values. The token represents the execution state of async function and can be used when users want to express dependencies on some side effects, e.g., the token becomes available once every thing in the func body is executed.

Example:

// Async function can't return void, it always must be some async thing.
async.func @async.0() -> !async.token {
  return
}

// Function returns only async value.
async.func @async.1() -> !async.value<i32> {
  %0 = arith.constant 42 : i32
  return %0 : i32
}

// Implicit token can be added to return types.
async.func @async.2() -> !async.token, !async.value<i32> {
  %0 = arith.constant 42 : i32
  return %0 : i32
}

Traits: IsolatedFromAbove

Interfaces: CallableOpInterface, FunctionOpInterface, OpAsmOpInterface, Symbol

Attributes: ¶

async.return (async::ReturnOp) ¶

Async function return operation

Syntax:

operation ::= `async.return` attr-dict ($operands^ `:` type($operands))?

The async.return is a special terminator operation for Async function.

Example:

async.func @foo() : !async.token {
  return
}

Traits: AlwaysSpeculatableImplTrait, HasParent<FuncOp>, ReturnLike, Terminator

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), RegionBranchTerminatorOpInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

async.runtime.add_ref (async::RuntimeAddRefOp) ¶

Adds a reference to async value

Syntax:

operation ::= `async.runtime.add_ref` $operand attr-dict `:` type($operand)

The async.runtime.add_ref operation adds a reference(s) to async value (token, value or group).

Attributes: ¶

Operands: ¶

async.runtime.add_to_group (async::RuntimeAddToGroupOp) ¶

Adds and async token or value to the group

Syntax:

operation ::= `async.runtime.add_to_group` $operand `,` $group attr-dict `:` type($operand)

The async.runtime.add_to_group adds an async token or value to the async group. Returns the rank of the added element in the group.

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.runtime.await (async::RuntimeAwaitOp) ¶

Blocks the caller thread until the operand becomes available

Syntax:

operation ::= `async.runtime.await` $operand attr-dict `:` type($operand)

The async.runtime.await operation blocks the caller thread until the operand becomes available or error.

Operands: ¶

async.runtime.await_and_resume (async::RuntimeAwaitAndResumeOp) ¶

Awaits the async operand and resumes the coroutine

Syntax:

operation ::= `async.runtime.await_and_resume` $operand `,` $handle attr-dict `:` type($operand)

The async.runtime.await_and_resume operation awaits for the operand to become available or error and resumes the coroutine on a thread managed by the runtime.

Operands: ¶

async.runtime.create (async::RuntimeCreateOp) ¶

Creates an async runtime token or value

Syntax:

operation ::= `async.runtime.create` attr-dict `:` type($result)

The async.runtime.create operation creates an async dialect token or value. Tokens and values are created in the non-ready state.

Results: ¶

async.runtime.create_group (async::RuntimeCreateGroupOp) ¶

Creates an async runtime group

Syntax:

operation ::= `async.runtime.create_group` $size `:` type($result) attr-dict

The async.runtime.create_group operation creates an async dialect group of the given size. Group created in the empty state.

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.runtime.drop_ref (async::RuntimeDropRefOp) ¶

Drops a reference to async value

Syntax:

operation ::= `async.runtime.drop_ref` $operand attr-dict `:` type($operand)

The async.runtime.drop_ref operation drops a reference(s) to async value (token, value or group).

Attributes: ¶

Operands: ¶

async.runtime.is_error (async::RuntimeIsErrorOp) ¶

Returns true if token, value or group is in error state

Syntax:

operation ::= `async.runtime.is_error` $operand attr-dict `:` type($operand)

The async.runtime.is_error operation returns true if the token, value or group (any of the async runtime values) is in the error state. It is the caller responsibility to check error state after the call to await or resuming after await_and_resume.

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.runtime.load (async::RuntimeLoadOp) ¶

Loads the value from the runtime async.value

Syntax:

operation ::= `async.runtime.load` $storage attr-dict `:` type($storage)

The async.runtime.load operation loads the value from the runtime async.value storage.

Interfaces: InferTypeOpInterface

Operands: ¶

Results: ¶

async.runtime.num_worker_threads (async::RuntimeNumWorkerThreadsOp) ¶

Gets the number of threads in the threadpool from the runtime

Syntax:

operation ::= `async.runtime.num_worker_threads` attr-dict `:` type($result)

The async.runtime.num_worker_threads operation gets the number of threads in the threadpool from the runtime.

Interfaces: InferTypeOpInterface

Results: ¶

async.runtime.resume (async::RuntimeResumeOp) ¶

Resumes the coroutine on a thread managed by the runtime

Syntax:

operation ::= `async.runtime.resume` $handle attr-dict

The async.runtime.resume operation resumes the coroutine on a thread managed by the runtime.

Operands: ¶

async.runtime.set_available (async::RuntimeSetAvailableOp) ¶

Switches token or value to available state

Syntax:

operation ::= `async.runtime.set_available` $operand attr-dict `:` type($operand)

The async.runtime.set_available operation switches async token or value state to available.

Operands: ¶

async.runtime.set_error (async::RuntimeSetErrorOp) ¶

Switches token or value to error state

Syntax:

operation ::= `async.runtime.set_error` $operand attr-dict `:` type($operand)

The async.runtime.set_error operation switches async token or value state to error.

Operands: ¶

async.runtime.store (async::RuntimeStoreOp) ¶

Stores the value into the runtime async.value

Syntax:

operation ::= `async.runtime.store` $value `,` $storage attr-dict `:` type($storage)

The async.runtime.store operation stores the value into the runtime async.value storage.

Operands: ¶

async.yield (async::YieldOp) ¶

Terminator for Async execute operation

Syntax:

operation ::= `async.yield` ($operands^ `:` type($operands))? attr-dict

The async.yield is a special terminator operation for the block inside async.execute operation.

Traits: AlwaysSpeculatableImplTrait, HasParent<ExecuteOp>, ReturnLike, Terminator

Interfaces: ConditionallySpeculatable, NoMemoryEffect (MemoryEffectOpInterface), RegionBranchTerminatorOpInterface

Effects: MemoryEffects::Effect{}

Operands: ¶

Types ¶

CoroHandleType ¶

coroutine handle

Syntax: !async.coro.handle

async.coro.handle is a handle to the coroutine (pointer to the coroutine frame) that can be passed around to resume or destroy the coroutine.

CoroIdType ¶

switched-resume coroutine identifier

Syntax: !async.coro.id

async.coro.id is a type identifying a switched-resume coroutine.

CoroStateType ¶

saved coroutine state

Syntax: !async.coro.state

async.coro.state is a saved coroutine state that should be passed to the coroutine suspension operation.

GroupType ¶

async group type

Syntax: !async.group

async.group represent a set of async tokens or values and allows to execute async operations on all of them together (e.g. wait for the completion of all/any of them).

TokenType ¶

async token type

Syntax: !async.token

async.token is a type returned by asynchronous operations, and it becomes available when the asynchronous operations that created it is completed.

ValueType ¶

async value type

async.value represents a value returned by asynchronous operations, which may or may not be available currently, but will be available at some point in the future.

Parameters: ¶