Struct ActorContext 

pub struct ActorContext(/* private fields */);

Shared actor runtime context.

This public surface is the foreign-runtime contract for rivetkit-core. Native Rust, NAPI-backed TypeScript, and future V8 runtimes should be able to drive actor behavior through ActorFactory plus the methods exposed here and on the returned runtime objects like SqliteDb, schedule APIs, queue APIs, ConnHandle, and WebSocket.

Implementations

impl ActorContext

pub async fn kv_batch_get(&self, keys: &[&[u8]]) -> Result<Vec<Option<Vec<u8>>>>

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub async fn kv_batch_put(&self, entries: &[(&[u8], &[u8])]) -> Result<()>

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub async fn kv_batch_delete(&self, keys: &[&[u8]]) -> Result<()>

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub async fn kv_delete_range(&self, start: &[u8], end: &[u8]) -> Result<()>

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub async fn kv_list_prefix( &self, prefix: &[u8], opts: ListOpts, ) -> Result<Vec<(Vec<u8>, Vec<u8>)>>

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub async fn kv_list_range( &self, start: &[u8], end: &[u8], opts: ListOpts, ) -> Result<Vec<(Vec<u8>, Vec<u8>)>>

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub fn kv(&self) -> &ActorKv

👎Deprecated:

Actor KV is deprecated. Use embedded SQLite (sql()) or actor state instead.

pub fn sql(&self) -> &SqliteDb

pub async fn db_exec(&self, sql: &str) -> Result<Vec<u8>>

pub async fn db_query( &self, sql: &str, params: Option<&[u8]>, ) -> Result<Vec<u8>>

pub async fn db_execute( &self, sql: &str, params: Option<&[u8]>, ) -> Result<Vec<u8>>

pub async fn db_run(&self, sql: &str, params: Option<&[u8]>) -> Result<()>

pub fn set_alarm(&self, timestamp_ms: Option<i64>) -> Result<()>

pub async fn init_alarms(&self)

Resync persisted alarms with the runtime’s alarm transport.

Foreign-runtime adapters should call this during startup after loading any persisted schedule state and before accepting user callbacks that rely on future alarms being armed.

pub fn queue(&self) -> &Self

pub fn sleep(&self) -> Result<()>

pub fn destroy(&self) -> Result<()>

pub fn stop_with_error(&self, message: impl Into<String>) -> Result<()>

Request a stop with an error attached. Behaves like Self::destroy locally (destroy grace hooks run for this generation), but the envoy reports the stop to the engine with StopCode::Error and the message, so the engine records the crash and applies its crash handling instead of unconditionally destroying the actor.

pub fn mark_destroy_requested(&self)

pub fn set_prevent_sleep(&self, _enabled: bool)

👎Deprecated:

no-op: use keep_awake or wait_until instead

Deprecated no-op. Use keep_awake to hold the actor awake for the duration of a future, or wait_until to keep work alive across the sleep grace period. Retained only for NAPI bridge compatibility.

pub fn prevent_sleep(&self) -> bool

👎Deprecated:

no-op: always returns false

pub fn wait_until(&self, future: impl Future<Output = ()> + Send + 'static)

pub fn register_task(&self, future: impl Future<Output = ()> + Send + 'static)

pub async fn keep_awake<F>(&self, future: F) -> F::Output

where F: Future,

pub fn keep_awake_region(&self) -> KeepAwakeRegion

pub async fn internal_keep_awake<F>(&self, future: F) -> F::Output

where F: Future,

pub fn keep_awake_count(&self) -> usize

pub fn internal_keep_awake_count(&self) -> usize

pub async fn track_work<F>(&self, kind: ActorWorkKind, future: F) -> F::Output

where F: Future,

pub fn spawn_work<F>(&self, kind: ActorWorkKind, future: F)

where F: Future<Output = ()> + Send + 'static,

pub fn begin_work_region(&self, kind: ActorWorkKind) -> ActorWorkRegion

pub fn actor_id(&self) -> &str

pub fn name(&self) -> &str

pub fn key(&self) -> &ActorKey

pub fn region(&self) -> &str

pub fn has_state(&self) -> bool

pub fn broadcast(&self, name: &str, args: &[u8])

pub fn conns(&self) -> ConnHandles<'_>

Returns a lock-backed iterator over live connections.

Do not hold the returned iterator across .await. It keeps a read lock on the connection map until dropped, which blocks connection writers.

pub fn client_endpoint(&self) -> Option<&str>

pub fn client_token(&self) -> Option<&str>

pub fn client_namespace(&self) -> Option<&str>

pub fn client_pool_name(&self) -> Option<&str>

pub fn ack_hibernatable_websocket_message( &self, gateway_id: &[u8], request_id: &[u8], server_message_index: u16, ) -> Result<()>

pub async fn drain_overdue_scheduled_events(&self) -> Result<()>

Dispatches any scheduled actions whose deadline has already passed.

Foreign-runtime adapters should call this after startup callbacks complete so overdue scheduled work enters the normal actor event loop.

pub async fn connect_conn_with_request<F>( &self, params: Vec<u8>, request: Option<Request>, create_state: F, ) -> Result<ConnHandle>

where F: Future<Output = Result<Vec<u8>>> + Send,

pub async fn disconnect_conn(&self, id: ConnId) -> Result<()>

pub async fn disconnect_conns<F>(&self, predicate: F) -> Result<()>

where F: FnMut(&ConnHandle) -> bool,

pub fn queue_hibernation_removal(&self, conn_id: impl Into<String>)

pub fn has_pending_hibernation_changes(&self) -> bool

pub fn take_pending_hibernation_changes(&self) -> Vec<ConnId>

pub fn dirty_hibernatable_conns(&self) -> Vec<ConnHandle>

pub fn inspector_snapshot(&self) -> InspectorSnapshot

pub fn is_destroy_requested(&self) -> bool

pub async fn wait_for_destroy_completion_public(&self)

pub async fn with_disconnect_callback<F, Fut, T>(&self, run: F) -> T

where F: FnOnce() -> Fut, Fut: Future<Output = T>,

pub fn websocket_callback_region(&self) -> WebSocketCallbackRegion

impl ActorContext

pub async fn send(&self, name: &str, body: &[u8]) -> Result<QueueMessage>

pub async fn enqueue_and_wait( &self, name: &str, body: &[u8], opts: EnqueueAndWaitOpts, ) -> Result<Option<Vec<u8>>>

pub async fn next(&self, opts: QueueNextOpts) -> Result<Option<QueueMessage>>

pub async fn next_batch( &self, opts: QueueNextBatchOpts, ) -> Result<Vec<QueueMessage>>

pub async fn wait_for_names( &self, names: Vec<String>, opts: QueueWaitOpts, ) -> Result<QueueMessage>

pub async fn wait_for_names_available( &self, names: Vec<String>, opts: QueueWaitOpts, ) -> Result<()>

pub fn try_next(&self, opts: QueueTryNextOpts) -> Result<Option<QueueMessage>>

pub fn try_next_batch( &self, opts: QueueTryNextBatchOpts, ) -> Result<Vec<QueueMessage>>

pub async fn inspect_messages(&self) -> Result<Vec<QueueMessage>>

pub fn max_size(&self) -> u32

pub async fn reset(&self) -> Result<()>

Removes all messages from the queue and resets the size counter.

impl ActorContext

pub async fn after( &self, duration: Duration, action_name: &str, args: &[u8], ) -> Result<String>

pub async fn at( &self, timestamp_ms: i64, action_name: &str, args: &[u8], ) -> Result<String>

pub async fn cancel_schedule(&self, event_id: &str) -> Result<bool>

pub async fn get_scheduled_event( &self, event_id: &str, ) -> Result<Option<ScheduledEventInfo>>

pub async fn list_scheduled_events(&self) -> Result<Vec<ScheduledEventInfo>>

pub async fn cron_set( &self, name: &str, expression: &str, timezone: Option<&str>, action_name: &str, args: &[u8], max_history: Option<i64>, ) -> Result<()>

pub async fn cron_every( &self, name: &str, interval_ms: i64, action_name: &str, args: &[u8], max_history: Option<i64>, ) -> Result<()>

pub async fn cron_delete(&self, name: &str) -> Result<bool>

pub async fn cron_get(&self, name: &str) -> Result<Option<CronJobInfo>>

pub async fn cron_list(&self) -> Result<Vec<CronJobInfo>>

pub async fn cron_history( &self, name: &str, limit: Option<i64>, ) -> Result<Vec<CronFire>>

impl ActorContext

pub async fn wait_for_tracked_shutdown_work(&self) -> bool

pub async fn wait_for_tracked_shutdown_work_unbounded(&self)

pub fn mark_core_dispatched_hook_completed(&self)

impl ActorContext

pub fn state(&self) -> Vec<u8>

pub fn set_state_initial(&self, state: Vec<u8>)

Foreign-runtime bootstrap hook for installing the actor state snapshot before the actor starts handling lifecycle/dispatch work.

pub fn request_save(&self, opts: RequestSaveOpts)

Fire-and-forget save request helper.

If the lifecycle event inbox is unavailable, this only logs a warning and returns. That warn! is the sole failure signal for this path; callers do not receive a Result. Call Self::request_save_and_wait when the caller must observe save-request delivery failures.

pub async fn request_save_and_wait(&self, opts: RequestSaveOpts) -> Result<()>

pub async fn save_state(&self, deltas: Vec<StateDelta>) -> Result<()>

pub async fn save_state_and_workflow_batch( &self, workflow_writes: Vec<WorkflowKvWrite>, ) -> Result<()>

Requests one logical workflow-engine flush. The actor lifecycle owns serializing actor state and committing both sides in one SQLite transaction.

pub fn begin_on_state_change(&self) -> OnStateChangeGuard

pub fn on_state_change_started(&self)

pub fn on_state_change_finished(&self)

pub fn persisted(&self) -> PersistedActor

pub fn load_persisted(&self, persisted: PersistedActor)

pub fn scheduled_events(&self) -> Vec<PersistedScheduleEvent>

pub fn set_scheduled_events( &self, scheduled_events: Vec<PersistedScheduleEvent>, )

pub fn set_input(&self, input: Option<Vec<u8>>)

pub fn input(&self) -> Option<Vec<u8>>

pub fn set_has_initialized(&self, has_initialized: bool)

pub fn has_initialized(&self) -> bool

pub fn flush_on_shutdown(&self)

pub fn on_request_save(&self, hook: Box<dyn Fn(RequestSaveOpts) + Send + Sync>)

Trait Implementations

impl Clone for ActorContext

fn clone(&self) -> ActorContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ActorContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.