Alpha ZealPHP is early-stage and under active development. APIs may change between minor versions until v1.0. Feedback and bug reports welcome on GitHub.
Esc
API Index — Namespaces, Packages, Reports, Indices

AtomicBackend
in package
implements CounterBackend

FinalYes

Default CounterBackend — wraps OpenSwoole\Atomic\Long (a 64-bit SIGNED atomic).

Each named counter gets a process-shared atomic; the map must be populated BEFORE workers fork (the shared memory segment is inherited). Lock-free reads, CAS-based compareAndSet. Uses the 64-bit Long variant rather than the 32-bit unsigned OpenSwoole\Atomic so a busy long-lived counter (a global request counter, etc.) can't silently wrap at 2^32 — its range is the full signed 64-bit space.

Table of Contents

Interfaces

CounterBackend
Behavioural contract for Counter backends.

Properties

$counters  : array<string, Long>

Methods

atomicFor()  : Long
Return the underlying Atomic for a named counter — used by the Counter facade's raw() BC method.
compareAndSet()  : bool
decr()  : int
expire()  : bool
Set TTL on a counter (N-3). Returns true if the TTL was applied.
get()  : int
incr()  : int
incrBounded()  : int|null
Bounded atomic increment (N-2). Increments by $by only if the resulting value would NOT exceed $maxBound. Returns the new value on success, or NULL when the cap would be exceeded (no-op).
mincr()  : array<string, int>
Batch increment (N-4). Pipelined where the backend supports it.
reset()  : void
set()  : bool
setIfAbsent()  : bool
Initialize a counter ONLY if it doesn't already exist (N-1).
atomic()  : Long

Properties

Methods

atomicFor()

Return the underlying Atomic for a named counter — used by the Counter facade's raw() BC method.

public atomicFor(string $name) : Long
Parameters
$name : string
Return values
Long

compareAndSet()

public compareAndSet(string $name, int $expected, int $new) : bool
Parameters
$name : string
$expected : int
$new : int
Return values
bool

decr()

public decr(string $name[, int $by = 1 ]) : int
Parameters
$name : string
$by : int = 1
Return values
int

expire()

Set TTL on a counter (N-3). Returns true if the TTL was applied.

public expire(string $name, int $seconds) : bool

Atomic backend: no-op (returns false — shared memory has no TTL; the counter lives until the master dies). Redis backend: EXPIRE on the underlying key.

Parameters
$name : string
$seconds : int
Return values
bool

get()

public get(string $name) : int
Parameters
$name : string
Return values
int

incr()

public incr(string $name[, int $by = 1 ]) : int
Parameters
$name : string
$by : int = 1
Return values
int

incrBounded()

Bounded atomic increment (N-2). Increments by $by only if the resulting value would NOT exceed $maxBound. Returns the new value on success, or NULL when the cap would be exceeded (no-op).

public incrBounded(string $name, int $by, int $maxBound) : int|null

Use case: rate-limit slots, pool counters where the cap matters.

Parameters
$name : string
$by : int
$maxBound : int
Return values
int|null

mincr()

Batch increment (N-4). Pipelined where the backend supports it.

public mincr(array<string|int, mixed> $deltas) : array<string, int>
Parameters
$deltas : array<string|int, mixed>

name → delta (defaults to 1 each)

Return values
array<string, int> —

name → new value (in input order)

reset()

public reset(string $name) : void
Parameters
$name : string

set()

public set(string $name, int $value) : bool
Parameters
$name : string
$value : int
Return values
bool

setIfAbsent()

Initialize a counter ONLY if it doesn't already exist (N-1).

public setIfAbsent(string $name, int $value) : bool

Returns true on first-time set; false if the counter already has a value (existing value is preserved).

Parameters
$name : string
$value : int
Return values
bool

atomic()

private atomic(string $name) : Long
Parameters
$name : string
Return values
Long
On this page