Nexus API Reference

Runtime
in

Abstraction over the concurrency backend that powers the actor system.

A Runtime provides the primitives — mailboxes, fiber/coroutine spawning, timers, cooperative yielding, and the main event loop — that the ActorSystem and ActorCell depend on. By programming to this interface, actor code is identical whether it runs on PHP Fibers (development), Swoole coroutines (production), or the deterministic StepRuntime (testing).

Three implementations ship in the core distribution:

  • FiberRuntime (nexus-runtime-fiber) — PHP Fiber-based, zero external dependencies.
  • SwooleRuntime (nexus-runtime-swoole) — Swoole coroutines with true async I/O.
  • StepRuntime (nexus-runtime-step) — Single-step, fully deterministic for tests.

Example:

$runtime = new FiberRuntime();
$system  = ActorSystem::create('my-app', $runtime);
$ref     = $system->spawn(Props::fromBehavior($behavior), 'worker');
$ref->tell(new DoWork());
$system->run(); // blocks until shutdown
Tags
see
ActorSystem

for the top-level entry point that consumes a Runtime

see
MailboxConfig

for configuring the mailboxes the runtime creates

see
Duration

for expressing delays and timeouts

psalm-api

Table of Contents

Methods

createFutureSlot()  : FutureSlot
Create a lightweight value slot for the ask pattern.
createMailbox()  : Mailbox<string|int, T>
Create a new mailbox governed by `$config`.
isRunning()  : bool
Return `true` if the runtime event loop is currently active.
name()  : string
Return the human-readable name that identifies this runtime implementation.
run()  : void
Start the runtime event loop and block until all actors have shut down.
scheduleOnce()  : Cancellable
Schedule `$callback` to run once after `$delay` has elapsed.
scheduleRepeatedly()  : Cancellable
Schedule `$callback` to run repeatedly, starting after `$initialDelay`.
shutdown()  : void
Initiate a graceful shutdown and wait up to `$timeout` for completion.
sleep()  : void
Suspend the current fiber or coroutine for `$duration`.
spawn()  : string
Spawn a new fiber or coroutine to run `$actorLoop`.
yield()  : void
Cooperatively yield execution to allow other fibers or coroutines to run.

Methods

createFutureSlot()

Create a lightweight value slot for the ask pattern.

public createFutureSlot() : FutureSlot

The caller is responsible for scheduling timeout failures.

Return values
FutureSlot

createMailbox()

Create a new mailbox governed by `$config`.

public createMailbox(MailboxConfig $config) : Mailbox<string|int, T>

The returned mailbox is bound to this runtime's concurrency model — e.g. a Fiber mailbox suspends fibers on dequeueBlocking(), while a Swoole mailbox blocks a coroutine on a Swoole channel.

Parameters
$config : MailboxConfig
Tags
template

T of object

Return values
Mailbox<string|int, T>

isRunning()

Return `true` if the runtime event loop is currently active.

public isRunning() : bool
Return values
bool

name()

Return the human-readable name that identifies this runtime implementation.

public name() : string
Return values
string

run()

Start the runtime event loop and block until all actors have shut down.

public run() : void

For FiberRuntime this drives the fiber scheduler. For SwooleRuntime this enters the Swoole event loop. Returns only after shutdown() completes.

scheduleOnce()

Schedule `$callback` to run once after `$delay` has elapsed.

public scheduleOnce(Duration $delay, callable $callback) : Cancellable

Returns a Cancellable that can be used to abort the pending callback before it fires. The callback is invoked in the runtime's execution context.

Parameters
$delay : Duration
$callback : callable
Return values
Cancellable

scheduleRepeatedly()

Schedule `$callback` to run repeatedly, starting after `$initialDelay`.

public scheduleRepeatedly(Duration $initialDelay, Duration $interval, callable $callback) : Cancellable

Subsequent invocations are spaced $interval apart. Returns a Cancellable to stop future invocations.

Parameters
$initialDelay : Duration
$interval : Duration
$callback : callable
Return values
Cancellable

shutdown()

Initiate a graceful shutdown and wait up to `$timeout` for completion.

public shutdown(Duration $timeout) : void

Signals all actors to stop, drains pending messages, and exits the event loop.

Parameters
$timeout : Duration

sleep()

Suspend the current fiber or coroutine for `$duration`.

public sleep(Duration $duration) : void

Unlike usleep(), this does not block the OS thread — other actors continue to process messages while this one sleeps.

Parameters
$duration : Duration

spawn()

Spawn a new fiber or coroutine to run `$actorLoop`.

public spawn(callable $actorLoop) : string

The runtime starts the loop immediately (or schedules it for the next tick) and returns an opaque identifier string for observability.

Parameters
$actorLoop : callable
Return values
string

yield()

Cooperatively yield execution to allow other fibers or coroutines to run.

public yield() : void

Called inside actor message loops to prevent one busy actor from starving others.


        

        
    




    

    

                                

                

                            
    

        On this page

        
    


                

                            

            

    

        

            
Search results