Categorygithub.com/blcksec/roadrunner
modulepackage
0.9.0
Repository: https://github.com/blcksec/roadrunner.git
Documentation: pkg.go.dev

# README

RoadRunner

GoDoc Build Status Go Report Card Scrutinizer Code Quality Codecov

High-performance PHP job balancer and process manager library for Golang.

Features:

  • no external dependencies or services, drop-in
  • load balancer, process manager and task pipeline
  • build for multiple frontends (queue, rest, psr-7, async php, etc)
  • works over TPC, unix sockets and standard pipes
  • automatic worker replacement and safe destruction
  • worker lifecycle management (create/allocate/destroy timeouts)
  • payload context and body
  • control over max jobs per worker
  • protocol, worker and job level error management (including PHP errors)
  • very fast (~250k calls per second on Ryzen 1700X over 16 threads)
  • works on Windows

Examples:

p, err := NewPool(
    func() *exec.Cmd { return exec.Command("php", "worker.php", "pipes") },
    NewPipeFactory(),
    Config{
        NumWorkers:      uint64(runtime.NumCPU()),
        AllocateTimeout: time.Second,              
        DestroyTimeout:  time.Second,               
    },
)
defer p.Destroy()

rsp, err := p.Exec(&Payload{Body: []byte("hello")})
<?php
/**
 * @var Goridge\RelayInterface $relay
 */

use Spiral\Goridge;
use Spiral\RoadRunner;

$rr = new RoadRunner\Worker($relay);

while ($body = $rr->receive($context)) {
    try {
        $rr->send((string)$body, (string)$context);
    } catch (\Throwable $e) {
        $rr->error((string)$e);
    }
}

Check how to init relay here.

License:

The MIT License (MIT). Please see LICENSE for more information.

# Functions

NewPipeFactory returns new factory instance and starts listening.
NewPool creates new worker pool and task multiplexer.
NewSocketFactory returns SocketFactory attached to a given socket listener.

# Constants

EventCreated thrown when new worker is spawned.
EventDestruct thrown before worker destruction.
EventError thrown any worker related even happen (error passed as context).
StateErrored - error state (can't be used).
StateInactive - no associated process.
StateReady - ready for job.
StateStopped - process has been terminated.
StateWorking - working on given payload.
StopRequest can be sent by worker to indicate that restart is required.

# Structs

Config defines basic behaviour of worker creation and handling process.
Payload carries binary header and body to workers and back to the server.
PipeFactory connects to workers using standard streams (STDIN, STDOUT pipes).
Pool controls worker creation, destruction and task routing.
SocketFactory connects to external workers using socket server.
Worker - supervised process with api over goridge.Relay.

# Interfaces

Factory is responsible of wrapping given command into tasks worker.
State represents worker status and updated time.

# Type aliases

JobError is job level error (no worker halt), wraps at top of error context.