erl

Documentation

Overview

erl programming system

the `erl` package wraps channels in a Process based system inspired by Erlang and the Open Telecom Platform (OTP), which is the correct way to build an Actor system on top of CSP.

For now all of OTP and the `gen` behaviours are left out, but the core language primatives needed to build are implemented here:

• process - wraps user code and responds to signals
• monitor/demonitor signal - allows a process to be notified when the other process exits
• link/unlink signal - joins two processes and causes them both to exit if either one does
• Exit Trap - allows a process to ignore an exit signal and convert it to a message signal that is sent to the user code.

This all works, but the API here may change as we expand into OTP behaviours.

Index

• func CancelTimer(tr TimerRef) error
• func DebugLogEnabled() bool
• func DebugPrintf(format string, v ...any)
• func DebugPrintln(v ...any)
• func Demonitor(self PID, ref Ref) bool
• func Exit(self PID, pid PID, reason *exitreason.S)
• func IsAlive(pid PID) bool
• func Link(self PID, pid PID)
• func NewTestReceiver(t *testing.T) (PID, *TestReceiver)
• func ProcessFlag(self PID, flag ProcFlag, value any)
• func Send(pid PID, term any)
• func SetDebugLog(v bool)
• func SpawnMonitor(self PID, r Runnable) (PID, Ref)
• func Unlink(self PID, pid PID)
• func Unregister(name Name) bool
• type Dest
• type DownMsg
• type ExitMsg
• type ILogger
• type Name
  • func (n Name) ResolvePID() (PID, error)
• type PID
  • func RootPID() PID
  • func Spawn(r Runnable) PID
  • func SpawnLink(self PID, r Runnable) PID
  • func WhereIs(name Name) (pid PID, exists bool)
  • func (self PID) Equals(pid PID) bool
  • func (pid PID) IsNil() bool
  • func (p PID) ResolvePID() (PID, error)
  • func (pid PID) String() string
• type PIDIface
• type ProcFlag
• type Process
  • func NewProcess(r Runnable) *Process
  • func (p *Process) String() string
• type Ref
  • func MakeRef() Ref
  • func Monitor(self PID, pid PID) Ref
• type Registration
  • func Registered() []Registration
• type RegistrationError
  • func Register(name Name, pid PID) *RegistrationError
  • func (e *RegistrationError) Error() string
• type RegistrationErrorKind
• type Runnable
• type Signal
  • func NewMsg(body any) Signal
• type TestReceiver
  • func (tr *TestReceiver) Loop(handler func(msg any) bool) bool
  • func (tr *TestReceiver) LoopFor(tout time.Duration, handler func(msg any) bool) error
  • func (tr *TestReceiver) Receive(self PID, inbox <-chan any) error
  • func (tr *TestReceiver) Receiver() <-chan any
• type TimerRef
  • func SendAfter(pid PID, term any, tout time.Duration) TimerRef

Functions

func CancelTimer

func CancelTimer(tr TimerRef) error

func DebugLogEnabled

func DebugLogEnabled() bool

func DebugPrintf

func DebugPrintf(format string, v ...any)

func DebugPrintln

func DebugPrintln(v ...any)

func Demonitor

func Demonitor(self PID, ref Ref) bool

Removes a Monitor

func Exit

func Exit(self PID, pid PID, reason *exitreason.S)

func IsAlive

func IsAlive(pid PID) bool

Returns true if the process is running

func Link

func Link(self PID, pid PID)

A Link is a bi-directional relationship between two processes. Once established, an exit signal in one process will always be sent to the other process. If you prefer to handle the ExitMsg in the Runnable, then use ProcessFlag (TrapExit, true)

To remove a link use Unlink

func NewTestReceiver

func NewTestReceiver(t *testing.T) (PID, *TestReceiver)

Deprecated: use [erltest.NewReceiver] as an alternative with the ability to set message expectations

func ProcessFlag

func ProcessFlag(self PID, flag ProcFlag, value any)

func Send

func Send(pid PID, term any)

Sends the [term] to the process identified by [pid]. Will not error if process does not exist and will not block the caller.

func SetDebugLog

func SetDebugLog(v bool)

func SpawnMonitor

func SpawnMonitor(self PID, r Runnable) (PID, Ref)

Like Spawn but also creates a Monitor

func Unlink

func Unlink(self PID, pid PID)

Removes a Link between two processes. No error is sent if the link does not exist.

func Unregister

func Unregister(name Name) bool

Unregister given Name. Returns false if Name is not registered

Types

type Dest

type Dest interface {
	ResolvePID() (PID, error)
}

type DownMsg

type DownMsg struct {
	Proc   PID
	Reason *exitreason.S
	Ref    Ref
}

type ExitMsg

type ExitMsg struct {
	// the process that sent the exit signal
	Proc   PID
	Reason *exitreason.S
	// whether the exit was caused by a link. If false, then this was sent via [Exit()]
	Link bool
}

type ILogger

type ILogger interface {
	Println(v ...any)
	Printf(format string, v ...any)
}

var Logger ILogger = log.New(os.Stdout, "erl-go", log.Ldate|log.Ltime|log.Lmicroseconds)

type Name

type Name string

func (Name) ResolvePID

func (n Name) ResolvePID() (PID, error)

type PID

type PID struct {
	// contains filtered or unexported fields
}

A Process Identifier; wraps the underlying Process so we can reference it without exposing Process internals or provide a named process registry in the future

var UndefinedPID PID = PID{}

func RootPID

func RootPID() PID

func Spawn

func Spawn(r Runnable) PID

Creates a process and returns a PID that can be used to monitor or link to other process.

func SpawnLink

func SpawnLink(self PID, r Runnable) PID

Like Spawn but also creates a Link between the two processes.

func WhereIs

func WhereIs(name Name) (pid PID, exists bool)

func (PID) Equals

func (self PID) Equals(pid PID) bool

func (PID) IsNil

func (pid PID) IsNil() bool

func (PID) ResolvePID

func (p PID) ResolvePID() (PID, error)

TODO: might want to return an error if p.status != running?

func (PID) String

func (pid PID) String() string

type PIDIface

type PIDIface interface {
	// contains filtered or unexported methods
}

type ProcFlag

type ProcFlag string

var TrapExit ProcFlag = "trap_exit"

type Process

type Process struct {
	// contains filtered or unexported fields
}

func NewProcess

func NewProcess(r Runnable) *Process

func (*Process) String

func (p *Process) String() string

type Ref

type Ref string

an opaque unique string. Don't rely on structure format or even size for that matter.

var UndefinedRef Ref = Ref("")

func MakeRef

func MakeRef() Ref

Returns an opqaue "unique" identifier. Not crypto unique. Callers should not depend on size and structure of the returned Ref

func Monitor

func Monitor(self PID, pid PID) Ref

This will establish a one-way relationship between [self] and [pid] and identified by the returned Ref. Once established, [self] will receive a DownMsg if the [pid] exits. Multiple Monitors between processes can be created (this is how synchronous communication between processes is handled)

type Registration

type Registration struct {
	Name Name
	PID  PID
}

func Registered

func Registered() []Registration

type RegistrationError

type RegistrationError struct {
	Kind RegistrationErrorKind
}

func Register

func Register(name Name, pid PID) *RegistrationError

func (*RegistrationError) Error

func (e *RegistrationError) Error() string

type RegistrationErrorKind

type RegistrationErrorKind string

const (
	// process is already registered with given name
	AlreadyRegistered RegistrationErrorKind = "already_registered"
	// another process already registered given name
	NameInUse RegistrationErrorKind = "name_used"
	// the process you're trying to register doesn't exist/is dead
	NoProc RegistrationErrorKind = "no_proc"
	// name is invalid and cannot be registered.
	BadName RegistrationErrorKind = "bad_name"
)

type Runnable

type Runnable interface {
	Receive(self PID, inbox <-chan any) error
}

A Process managed

type Signal

type Signal interface {
	SignalName() string
}

func NewMsg

func NewMsg(body any) Signal

type TestReceiver

type TestReceiver struct {
	// contains filtered or unexported fields
}

func (*TestReceiver) Loop

func (tr *TestReceiver) Loop(handler func(msg any) bool) bool

func (*TestReceiver) LoopFor

func (tr *TestReceiver) LoopFor(tout time.Duration, handler func(msg any) bool) error

Like [Loop] but exit after [tout]

func (*TestReceiver) Receive

func (tr *TestReceiver) Receive(self PID, inbox <-chan any) error

func (*TestReceiver) Receiver

func (tr *TestReceiver) Receiver() <-chan any

type TimerRef

type TimerRef struct {
	// contains filtered or unexported fields
}

func SendAfter

func SendAfter(pid PID, term any, tout time.Duration) TimerRef