Nexus API Reference

StepRuntime
in package
implements Runtime

FinalYes

Deterministic runtime for testing.

Uses PHP Fibers internally but gives the test full control over execution:

  • step() processes exactly one message
  • drain() processes all pending messages
  • advanceTime() moves virtual clock and fires timers

No real concurrency, no real time, fully deterministic.

Tags
psalm-api

Table of Contents

Interfaces

Runtime
Abstraction over the concurrency backend that powers the actor system.

Methods

__construct()  : mixed
advanceTime()  : void
Advance the virtual clock and fire any timers that have matured.
clock()  : VirtualClock
createFutureSlot()  : FutureSlot
Create a lightweight value slot for the ask pattern.
createMailbox()  : Mailbox<string|int, TM>
Create a new mailbox governed by `$config`.
drain()  : void
Process all pending messages until no actor has work to do.
isIdle()  : bool
isRunning()  : bool
Return `true` if the runtime event loop is currently active.
name()  : string
Return the human-readable name that identifies this runtime implementation.
pendingMessageCount()  : int
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`.
step()  : bool
Process exactly one message from one actor.
yield()  : void
Cooperatively yield execution to allow other fibers or coroutines to run.

Methods

advanceTime()

Advance the virtual clock and fire any timers that have matured.

public advanceTime(Duration $duration) : void
Parameters
$duration : Duration

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, TM>
Parameters
$config : MailboxConfig
Tags
template

TM of object

Return values
Mailbox<string|int, TM>

drain()

Process all pending messages until no actor has work to do.

public drain() : void

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

pendingMessageCount()

public pendingMessageCount() : int
Return values
int

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

step()

Process exactly one message from one actor.

public step() : bool

Returns true if a message was processed, false if all actors are idle. Actors are checked in creation order (deterministic).

Return values
bool

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