Module me.ahoo.cosid.core

Package me.ahoo.cosid.internal

Class TimeSequencer

java.lang.Object

me.ahoo.cosid.internal.TimeSequencer

public final class TimeSequencer
extends Object

The sequencer of a time-based generator (03-core-model.md §4.1, 05-machine-lease.md §4.1).

The state of a binding is one long, time << seqBits | seq of the last issued id, next to that binding (TimeSequencer.Bound). A new binding of the slot swaps in a new Bound, which resets the sequence; the replaced state is retired to CLOSED. close() swaps in a terminal Bound and retires the last state, which gives the exact last issued time.

Issuing is a short critical section: read the binding and the time, check the window, compute and publish the state. Nothing waits inside it (01 §2.1): an attempt that has to wait (sequence exhausted, clock regression, slot floor, renewal at the ceiling) returns, the lock is released, the thread waits, then retries. Listener calls happen outside the lock too. A lock beats a CAS loop here: under contention the lock keeps the state in one core's cache while it issues, where every lost CAS moves it (benchmark P1, 16 threads).

Constructor Summary

Constructors

Constructor	Description
TimeSequencer(String name, Layout layout, SlotHandle slot, int nodeOffset, TimeSource time, ClockRegressionPolicy regression, GeneratorListener listener)	A sequencer whose node is the slot plus an offset (api-freeze.md §2.1.1).
TimeSequencer(String name, Layout layout, SlotHandle slot, TimeSource time, ClockRegressionPolicy regression, GeneratorListener listener)	A sequencer.

Method Summary

Modifier and Type	Method	Description
void	close()	Moves the sequencer to its terminal state: no id is issued once this returns.
long	lastIssuedMillis()	The time of the last issued id.
long	nextId()	Issues the next id; the layout must fit a long.
IdParts	nextParts()	Issues the next id as parts.
int	slot()	The slot of the current binding.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TimeSequencer

public TimeSequencer(String name,
 Layout layout,
 SlotHandle slot,
 TimeSource time,
 ClockRegressionPolicy regression,
 GeneratorListener listener)

A sequencer.

Parameters:

name - the generator name

layout - the id layout

slot - the machine slot

time - the time source

regression - the clock regression policy

listener - the event listener

TimeSequencer

public TimeSequencer(String name,
 Layout layout,
 SlotHandle slot,
 int nodeOffset,
 TimeSource time,
 ClockRegressionPolicy regression,
 GeneratorListener listener)

A sequencer whose node is the slot plus an offset (api-freeze.md §2.1.1).

Parameters:

name - the generator name

layout - the id layout

slot - the machine slot

nodeOffset - added to the slot to give the node of the ids, not negative

time - the time source

regression - the clock regression policy

listener - the event listener

Method Details

nextId

public long nextId()

Issues the next id; the layout must fit a long.

Returns:

the id

nextParts

public IdParts nextParts()

Issues the next id as parts.

Returns:

the parts

slot

public int slot()

The slot of the current binding.

Returns:

the slot

lastIssuedMillis

public long lastIssuedMillis()

The time of the last issued id.

Returns:

milliseconds since the Unix epoch, 0 when none was issued; exact once close() returned

close

public void close()

Moves the sequencer to its terminal state: no id is issued once this returns.