Scheduling a Future Agent Invocation (Scala)

Overview

A scheduled invocation enqueues a method call on the target agent to be executed at a specific future time. The call returns immediately; the target agent processes it when the scheduled time arrives.

Usage

For stream-free methods, .scheduleAt(when) enqueues the call for the given time. Durable guest clients return Future[Unit]; ephemeral guest clients return Future[InvocationReceipt] with invocation metadata. Return or compose the future to observe enqueue errors; it does not await execution of the scheduled method.


import golem.Datetime
 
val counter = CounterAgentClient.get("my-counter")
 
// Schedule increment to run 5 seconds from now
counter.increment.scheduleAt(Datetime.afterSeconds(5))
 
// Schedule with arguments — method params first, then when
val reporter = ReportAgentClient.get("daily")
reporter.generateReport.scheduleAt(
  "summary",
  when = Datetime.afterSeconds(3600) // 1 hour from now
)

Datetime Helper

The golem.Datetime type provides helper methods:


import golem.Datetime
 
Datetime.afterSeconds(60)     // 60 seconds from now
Datetime.afterSeconds(3600)   // 1 hour from now

Cancelable Variant

For a durable, stream-free target, scheduleCancelableAt returns Future[CancellationToken]. Ephemeral guest clients instead return Future[CancelableInvocationReceipt] (golem.runtime.rpc), which carries metadata and a cancellation token. Use asynchronous composition in Scala.js, never Await.result:


import golem.runtime.rpc.CancellationToken
import scala.concurrent.{ExecutionContext, Future}
 
given ExecutionContext = ExecutionContext.parasitic
var pending: Option[CancellationToken] = None
 
val scheduled: Future[Unit] =
  counter.increment.scheduleCancelableAt(Datetime.afterSeconds(60)).map { token =>
    pending = Some(token)
  }
 
// From a later invocation, after scheduled has completed:
def cancelPending(): Unit = {
  pending.foreach(_.cancel())
  pending = None
}

Use Cases

Periodic tasks: Schedule the next run at the end of each invocation
Delayed processing: Process an order after a cooling-off period
Reminders and notifications: Send a reminder at a specific time
Retry with backoff: Schedule a retry after a delay on failure