feat(pbs): add array-backed Stack and circular Queue
This commit is contained in:
@@ -176,6 +176,7 @@ faults. List itself rejects directly optional elements.
|
||||
## Reuse, costs and conformance
|
||||
|
||||
The shared implementation is independent of List representation.
|
||||
[Stack/Queue](sdk-stack-and-queue.md) capture in their LIFO/FIFO removal orders.
|
||||
[Linked](sdk-linked-and-cursor.md) uses Cursor<T> for forward and reverse captures.
|
||||
[Set](sdk-set-and-identity.md) produces Cursor<T>; Map<K,V> uses
|
||||
Cursor<keyval<K,V>> as specified by [Map/Keyval](sdk-map-and-keyval.md).
|
||||
|
||||
@@ -0,0 +1,135 @@
|
||||
# SDK Stack and Queue
|
||||
|
||||
Owner: `compiler/pbs`. Algorithms execute as PBS SDK source over existing typed
|
||||
storage, complete-group copies, terminal checks and shared snapshot Cursor.
|
||||
This contract builds on [Array/optional](typed-arrays-and-optional-execution.md),
|
||||
[generic structs](generic-structs-and-free-functions.md) and
|
||||
[List/shared Cursor](sdk-list-and-cursor.md#cursor-protocol).
|
||||
|
||||
## Types, identity and construction
|
||||
|
||||
`@sdk:collections` exports ordinary invariant nominal structs `stack<T>` and
|
||||
`queue<T>`. Directly optional T, including grouping, is invalid; optional of the
|
||||
collection and valid payloads containing optional fields remain valid. Tuple,
|
||||
native, contract, function and reference groups retain their complete types and
|
||||
owners. No extra cell per element circumvents Array's optional restriction.
|
||||
Project homonyms/copied metadata acquire no SDK authority. Imports, aliases,
|
||||
reexports and specializations preserve original SDK identity and privacy.
|
||||
|
||||
`new stack<T>()` / `new queue<T>()` create size zero and capacity 16. Their
|
||||
one-argument constructors create size zero and exactly that capacity, including
|
||||
zero. Diamond/omitted type arguments require an expected concrete application;
|
||||
values do not infer T. Capacity accepts int/long with localized lossless promotion,
|
||||
without general conversion/truncation. Negative/above-u32 capacity is rejected.
|
||||
|
||||
Collection references have stable identity through backing replacement. Assignment
|
||||
and parameter passing share mutations. Payload objects remain shared instances;
|
||||
duplicates and repeated aliases are separate occurrences, without deep copies or
|
||||
structural equality. Storage, start, length and private helpers are inaccessible.
|
||||
|
||||
## Public API
|
||||
|
||||
| Collection | Operation | Result and behavior |
|
||||
| --- | --- | --- |
|
||||
| Both | size() | long count of present occurrences |
|
||||
| Both | capacity() | long physical backing length |
|
||||
| Both | isEmpty() | bool, size equals zero |
|
||||
| Both | peek() | optional T, next removal value; none when empty |
|
||||
| Both | clear() | unit, discard contents and preserve capacity |
|
||||
| Both | cursor() | Cursor<T>, complete removal-order snapshot |
|
||||
| Stack | push(value: T) | unit, append at top |
|
||||
| Stack | pop() | optional T, remove top; none when empty |
|
||||
| Queue | enqueue(value: T) | unit, append at back |
|
||||
| Queue | dequeue() | optional T, remove front; none when empty |
|
||||
|
||||
Stack consumes LIFO, Queue FIFO. Receiver/arguments evaluate once in source order,
|
||||
including named calls. Zero/false are present. Faults remain faults, never absence.
|
||||
No indexer, holes, reserve/trim/resize, bounded/bulk variant, public nodes or
|
||||
mutation/reset through Cursor exists.
|
||||
|
||||
## Capacity and private storage
|
||||
|
||||
`0 <= size <= capacity <= 4294967295`. Initial capacity does not cap collection size.
|
||||
When required r exceeds c, automatic growth chooses
|
||||
`min(4294967295, max(r, c + max(1, ceil(c/2))))`, after checking r itself fits.
|
||||
Arithmetic uses checked long values without narrowing; zero grows to one.
|
||||
Invalid logical requests terminate through the private SDK TRAP_EXPLICIT binding
|
||||
with source attribution. Actual Array instructions retain their physical faults.
|
||||
Ordinary quotas can refuse earlier. Removal/clear never shrink capacity.
|
||||
|
||||
Stack owns a dense array occupying exactly `[0,size)`, with top at size-1.
|
||||
Queue owns a circular array occupying size logical positions from start. Empty
|
||||
Queue has start zero; otherwise capacity is positive and start is below capacity.
|
||||
Circular addressing avoids zero-capacity access/remainder. Every inactive slot is
|
||||
empty after successful operations. Neither collection is a List/Linked adapter;
|
||||
inclusion creates no collection node and dequeue never shifts remaining values.
|
||||
|
||||
Stack growth privately copies its dense prefix and inserts the value. Queue
|
||||
growth privately copies occupied suffix and wrapped prefix directly into `[0,size)`,
|
||||
then inserts at size; it installs backing, start=0 and size in that sequence.
|
||||
Old storage is not edited during candidate preparation. Complete groups and payload
|
||||
identities survive copies, including native owners. In-capacity insertion does not
|
||||
rebuild the whole backing. End operations without growth cost O(1) apart from normal
|
||||
value/carrier work; growth and clear cost O(n), plus physical capacity allocation.
|
||||
|
||||
## Mutation phases and lifetime
|
||||
|
||||
Prepare checks, next count, payloads, optional returns (including typed absence)
|
||||
and candidates before visible mutation. Source-selected write sequences are:
|
||||
|
||||
| Operation | Writes after preparation |
|
||||
| --- | --- |
|
||||
| In-capacity push/enqueue | Inactive destination slot, then size |
|
||||
| Growing push | Prepared backing, then size |
|
||||
| Growing enqueue | Prepared backing, start=0, then size |
|
||||
| Nonempty pop | Clear old top, then size |
|
||||
| Nonempty dequeue | Clear front, next start (zero when empty), then size |
|
||||
| Stack clear | Clear occupied slots in index order, then size=0 |
|
||||
| Queue clear | Clear occupied slots in FIFO order, then start=0, then size=0 |
|
||||
|
||||
Reads, capture and empty removals do not write the collection. Before the first
|
||||
visible write, rejection/preparation refusal preserves old backing, slots, start
|
||||
and size; argument effects/provisional allocations are not undone. Success restores
|
||||
all invariants. Later internal/resource faults may retain writes and incomplete
|
||||
invariants, without rollback, safe reuse, retry or recovery. Per-instruction refusal
|
||||
preserves its own entry state, not earlier instructions. No callback/explicit
|
||||
suspension occurs between update stores. Budget/debugger pauses remain resumable
|
||||
instruction boundaries; a method is not an atomic host observation region.
|
||||
|
||||
Removal clears the discarded slot; clear removes all occupied references while
|
||||
retaining empty backing. Later reuse cannot resurrect old payloads. Old/candidate
|
||||
arrays, multi-slot packing, optional carriers, copy scratch and snapshots coexist
|
||||
under unchanged quotas/GC. No allocation-free insertion/result, immediate collection
|
||||
or immediate quota return is promised.
|
||||
|
||||
## Removal-order snapshot Cursor
|
||||
|
||||
Stack captures top → base, Queue front → back. Inserting 20,22 yields Stack
|
||||
snapshot 22,20 and Queue snapshot 20,22. Capture completes before returning and
|
||||
owns one immutable private singly linked non-circular node per occurrence, with
|
||||
no snapshot array/source-slot association. It costs O(n) work/additional nodes;
|
||||
refusal returns no partial Cursor and leaves the source unchanged.
|
||||
|
||||
Reuse the entire shared table: a nonempty Cursor starts on first; hasNext tests
|
||||
successor; next without successor does nothing; only empty-born current is none.
|
||||
Consume current before deciding whether to advance. Captured sequence/order is
|
||||
independent of later insertion/removal/growth/clear; referenced objects still share
|
||||
later field changes. Consumed prefixes can become collectible, while final current
|
||||
node/value remain retained until the Cursor releases them.
|
||||
|
||||
## Conformance and distribution
|
||||
|
||||
Qualify real PBS through common IR/PBX and production loader/VM, using ordinary
|
||||
and optimized producers and runtime debug/release profiles. Cover complete APIs,
|
||||
context/types/origin/privacy, exact capacities/growth/maximum checks, zero/false,
|
||||
complete groups and ownership, order/duplicates/aliases, source/named evaluation,
|
||||
wrap-around/wrapped growth, fill/drain/reuse, snapshots and sharing.
|
||||
Measure coexisting arrays/carriers, quota preparation/write boundaries with
|
||||
independent original-object observations and successful-prefix comparisons. Keep
|
||||
explicit test-only post-write probes separate from natural refusal frequencies.
|
||||
Observe actual GC collections for discarded values/replaced backings and snapshot
|
||||
prefix/final release. Ship this spec and executable example in installed knowledge,
|
||||
compile real installed-JAR examples outside the checkout and execute emitted PBX.
|
||||
Regress shared storage/generic/Cursor behavior; retain provenance and limitations.
|
||||
|
||||
Runtime storage, ISA, quotas, faults and GC remain unchanged provider contracts.
|
||||
Reference in New Issue
Block a user