MLIR

Multi-Level IR Compiler Framework

'async' Dialect

Types and operations for async dialect This dialect contains operations for modeling asynchronous execution.

Type constraint definition 

coroutine 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.

switched-resume coroutine identifier 

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

saved coroutine state 

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

async group type 

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).

async token type 

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

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.

Operation definition 

async.add_to_group (::mlir::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
%1 = ... : !async.token
%2 = async.add_to_group %1, %0 : !async.token

Operands: 

OperandDescription
operandasync value type or async token type
groupasync group type

Results: 

ResultDescription
rankindex

async.await_all (::mlir::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

%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: 

OperandDescription
operandasync group type

async.await (::mlir::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: 

OperandDescription
operandasync value type or async token type

Results: 

ResultDescription
resultany type

async.coro.begin (::mlir::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.

Operands: 

OperandDescription
idswitched-resume coroutine identifier

Results: 

ResultDescription
handlecoroutine handle

async.coro.end (::mlir::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: 

OperandDescription
handlecoroutine handle

async.coro.free (::mlir::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: 

OperandDescription
idswitched-resume coroutine identifier
handlecoroutine handle

async.coro.id (::mlir::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.

Results: 

ResultDescription
idswitched-resume coroutine identifier

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

saves the coroutine state

Syntax:

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

The async.coro.saves saves the coroutine state.

Operands: 

OperandDescription
handlecoroutine handle

Results: 

ResultDescription
statesaved coroutine state

async.coro.suspend (::mlir::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.

Operands: 

OperandDescription
statesaved coroutine state

Successors: 

SuccessorDescription
suspendDestany successor
resumeDestany successor
cleanupDestany successor

async.create_group (::mlir::async::CreateGroupOp) 

creates an empty async group

Syntax:

operation ::= `async.create_group` attr-dict

The async.create_group allocates an empty async group. Async tokens or values can be added to this group later.

Example:

%0 = async.create_group
...
async.await_all %0

Results: 

ResultDescription
resultasync group type

async.execute (::mlir::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.executeoperation takesasync.tokendependencies andasync.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.

Operands: 

OperandDescription
dependenciesasync token type
operandsasync value type or async token type

Results: 

ResultDescription
tokenasync token type
resultsasync value type

async.runtime.add_ref (::mlir::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: 

AttributeMLIR TypeDescription
count::mlir::IntegerAttr32-bit signless integer attribute whose value is positive

Operands: 

OperandDescription
operandasync value type or async token type or async group type

async.runtime.add_to_group (::mlir::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.

Operands: 

OperandDescription
operandasync value type or async token type
groupasync group type

Results: 

ResultDescription
rankindex

async.runtime.await_and_resume (::mlir::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 and resumes the coroutine on a thread managed by the runtime.

Operands: 

OperandDescription
operandasync value type or async token type or async group type
handlecoroutine handle

async.runtime.await (::mlir::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.

Operands: 

OperandDescription
operandasync value type or async token type or async group type

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

creates an async runtime value (token, value or group)

Syntax:

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

The async.runtime.create operation creates an async dialect value (token, value or group). Tokens and values are created in non-ready state. Groups are created in empty state.

Results: 

ResultDescription
resultasync value type or async token type or async group type

async.runtime.drop_ref (::mlir::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: 

AttributeMLIR TypeDescription
count::mlir::IntegerAttr32-bit signless integer attribute whose value is positive

Operands: 

OperandDescription
operandasync value type or async token type or async group type

async.runtime.load (::mlir::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.

Operands: 

OperandDescription
storageasync value type

Results: 

ResultDescription
resultany type

async.runtime.resume (::mlir::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: 

OperandDescription
handlecoroutine handle

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

switches token or value 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: 

OperandDescription
operandasync value type or async token type

async.runtime.store (::mlir::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: 

OperandDescription
valueany type
storageasync value type

async.yield (::mlir::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.

Operands: 

OperandDescription
operandsany type

Type definition 

Async_CoroHandleType (CoroHandleType) 

coroutine 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.

Async_CoroIdType (CoroIdType) 

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

Async_CoroStateType (CoroStateType) 

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

Async_GroupType (GroupType) 

async group type 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).

Async_TokenType (TokenType) 

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

Async_ValueType (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.

Type parameters: 

ParameterC++ typeDescription
valueTypeValueType