Awakeables

Awakeables pause an invocation while waiting for another process to complete a task. You can use this pattern to let a handler execute a task somewhere else and retrieve the result. This pattern is also known as the callback (task token) pattern.

Java

MyHandler.java

Awakeable<String> awakeable = ctx.awakeable(JsonSerdes.STRING);

String awakeableId = awakeable.id();

ctx.run(() -> triggerTaskAndDeliverId(awakeableId));

String payload = awakeable.await();

1. The handler creates an awakeable. This contains a String identifier and a Promise/Awaitable.
2. The handler triggers a task/process and attaches the awakeable ID (e.g. over Kafka, via HTTP,...). For example, send an HTTP request to a service that executes the task, and attach the ID to the payload. You use ctx.run to avoid retriggering the task this on retries.
3. The handler waits until the other process has executed the task.

4. The external process completes the awakeable when the task is finished by:

   resolve_with_curl.sh

   reject_with_curl.sh

   ExternalProcessResolve.java

   ExternalProcessReject.java

   
   

   curl localhost:8080/restate/awakeables/prom_1PePOqp/resolve -H 'content-type: application/json'

   -d '{"hello": "world"}'

   
   
   • Resolves the awakeable
     • Over HTTP with its ID and an optional payload
     • Via the SDK with its ID and an optional payload
   • Rejects the awakeable with its ID and a reason: failure. This throws a terminal error in the waiting handler.
     • Over HTTP with its ID and an optional payload
     • Via the SDK with its ID and an optional payload

5. Once the ID has been returned to the service, the invocation resumes.

Kotlin

MyHandler.kt

val awakeable = ctx.awakeable<String>()

val awakeableId: String = awakeable.id

ctx.runBlock{ triggerTaskAndDeliverId(awakeableId) }

val payload: String = awakeable.await()

1. The handler creates an awakeable. This contains a String identifier and a Promise/Awaitable.
2. The handler triggers a task/process and attaches the awakeable ID (e.g. over Kafka, via HTTP,...). For example, send an HTTP request to a service that executes the task, and attach the ID to the payload. You use ctx.run to avoid retriggering the task this on retries.
3. The handler waits until the other process has executed the task.

4. The external process completes the awakeable when the task is finished by:

   resolve_curl.sh

   reject_curl.sh

   ExternalProcessResolve.kt

   ExternalProcessReject.kt

   
   

   curl localhost:8080/restate/awakeables/prom_1PePOqp/resolve -H 'content-type: application/json'

   -d '{"hello": "world"}'

   
   
   • Resolving the awakeable
     • Over HTTP with its ID and an optional payload
     • Via the SDK with its ID and an optional payload
   • Rejecting the awakeable. This throws a terminal error in the waiting handler.
     • Over HTTP with its ID and a failure reason
     • Via the SDK with its ID and a failure reason

5. The handler receives the payload and resumes.

Java

Specifying the serializer

For primitive types, you can use the Restate SDK's CoreSerdes. For other types, have a look at the serialization docs.

Kotlin

Specifying the serializer

By default JSON is used to serialize payloads, using Kotlin serialization. For other types, have a look at the serialization docs.

Cost savings on FaaS

When running on Function-as-a-Service platforms, such as AWS Lambda, Restate suspends the handler while waiting for the awakeable to be completed. Since you only pay for the time that the handler is actually running, your don't pay while waiting for the external process to return.

Awaiting awakeables in Virtual Objects

Virtual Objects only process a single invocation at a time, so the Virtual Object will be blocked while waiting on the awakeable to be resolved.