The identifier-pool Reference Manual

This is the identifier-pool Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Tue Nov 15 06:04:53 2022 GMT+0.

1 Introduction

identifier-pool

A simple generational identification number allocator.

Overview

This library is able to generate increasing identifiers (integers) in such a way that previously deallocated identifiers are available to be reclaimed by the generator the next time one is allocated. Essentially, it solves the "ABA Problem": https://en.wikipedia.org/wiki/ABA_problem

It does so in a space-efficient manner, without the need for the storage of a list of deallocated identifiers. It does this by keeping deallocated identifiers around and modifying their data on deletion to build a sort of implicit linked list. That is, when an identifier is marked for deletion, the following occurs:

The packed version portion of its data is incremented.
The packed ID portion of its data is set to the integer stored in the pool's FREE-HEAD slot (FREE-HEAD can be thought of as the head of the implicit linked list). If FREE-HEAD is null, then instead, all of the bits of the ID are set. #xFFFFFF represents the "invalid" ID.
FREE-HEAD is set to the ID portion of its data.

This, in effect, constructs an implicit linked list of the next available identifiers that can be generated.

Install

(ql:quickload :identifier-pool)

License

Licensed under the MIT License.

2 Systems

The main system appears first, followed by any subsystem dependency.

identifier-pool

2.1 `identifier-pool`

A simple generational identification number allocator.

Author

Michael Fiano <mail@mfiano.net>

Home Page

https://git.mfiano.net/mfiano/identifier-pool

License

MIT

Version

0.1.0

Dependencies

dynamic-array (system).
mfiano-utils (system).

Source

identifier-pool.asd.

Child Components

package.lisp (file).
identifier-pool.lisp (file).

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Lisp

3.1.1 `identifier-pool/identifier-pool.asd`

Source: identifier-pool.asd.
Parent Component: identifier-pool (system).
ASDF Systems: identifier-pool.

3.1.2 `identifier-pool/package.lisp`

Source: identifier-pool.asd.
Parent Component: identifier-pool (system).
Packages: identifier-pool.

3.1.3 `identifier-pool/identifier-pool.lisp`

Dependency

package.lisp (file).

Source

identifier-pool.asd.

Parent Component

identifier-pool (system).

Public Interface

active-p (function).
count (reader).
(setf count) (writer).
free (function).
generate (function).
id (function).
make-pool (function).
map (function).
version (function).

Internals

%make-pool (function).
+id-bits+ (constant).
+id-mask+ (constant).
+version-bits+ (constant).
+version-mask+ (constant).
free-head (reader).
(setf free-head) (writer).
pack (function).
pool (structure).
store (reader).
(setf store) (writer).
unpack (function).

4 Packages

Packages are listed by definition order.

identifier-pool

4.1 `identifier-pool`

Source

package.lisp.

Use List

common-lisp.

Public Interface

active-p (function).
count (reader).
(setf count) (writer).
free (function).
generate (function).
id (function).
make-pool (function).
map (function).
version (function).

Internals

%make-pool (function).
+id-bits+ (constant).
+id-mask+ (constant).
+version-bits+ (constant).
+version-mask+ (constant).
free-head (reader).
(setf free-head) (writer).
pack (function).
pool (structure).
store (reader).
(setf store) (writer).
unpack (function).

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Public Interface
Internals

5.1 Public Interface

Ordinary functions

5.1.1 Ordinary functions

Function: active-p (pool identifier) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Reader: count (instance) ¶

Writer: (setf count) (instance) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.
Target Slot: count.

Function: free (pool identifier) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Function: generate (pool) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Function: id (identifier) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Function: make-pool (&key capacity) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Function: map (pool func) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Function: version (identifier) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

5.2 Internals

Constants
Ordinary functions
Structures

5.2.1 Constants

Constant: +id-bits+ ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Constant: +id-mask+ ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Constant: +version-bits+ ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Constant: +version-mask+ ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

5.2.2 Ordinary functions

Function: %make-pool (&key store free-head count) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Reader: free-head (instance) ¶

Writer: (setf free-head) (instance) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.
Target Slot: free-head.

Function: pack (id version) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

Reader: store (instance) ¶

Writer: (setf store) (instance) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.
Target Slot: store.

Function: unpack (identifier) ¶

Package: identifier-pool.
Source: identifier-pool.lisp.

5.2.3 Structures

Structure: pool ¶

Package

identifier-pool.

Source

identifier-pool.lisp.

Direct superclasses

structure-object.

Direct slots

Slot: store ¶

Type: dynamic-array:dynamic-array
Initform: (dynamic-array:make-array)
Readers: store.
Writers: (setf store).

Slot: free-head ¶

Readers: free-head.
Writers: (setf free-head).

Slot: count ¶

Type: mfiano-utils:ub24
Initform: 0
Readers: count.
Writers: (setf count).

Appendix A Indexes

Concepts
Functions
Variables
Data types

A.1 Concepts

A.2 Functions

Jump to:	% ( A C F G I M P S U V

	Index Entry	Section

%
	`%make-pool`:	Private ordinary functions

(
	`(setf count)`:	Public ordinary functions
	`(setf free-head)`:	Private ordinary functions
	`(setf store)`:	Private ordinary functions

A
	`active-p`:	Public ordinary functions

C
	`count`:	Public ordinary functions

F
	`free`:	Public ordinary functions
	`free-head`:	Private ordinary functions
	`Function, %make-pool`:	Private ordinary functions
	`Function, (setf count)`:	Public ordinary functions
	`Function, (setf free-head)`:	Private ordinary functions
	`Function, (setf store)`:	Private ordinary functions
	`Function, active-p`:	Public ordinary functions
	`Function, count`:	Public ordinary functions
	`Function, free`:	Public ordinary functions
	`Function, free-head`:	Private ordinary functions
	`Function, generate`:	Public ordinary functions
	`Function, id`:	Public ordinary functions
	`Function, make-pool`:	Public ordinary functions
	`Function, map`:	Public ordinary functions
	`Function, pack`:	Private ordinary functions
	`Function, store`:	Private ordinary functions
	`Function, unpack`:	Private ordinary functions
	`Function, version`:	Public ordinary functions

G
	`generate`:	Public ordinary functions

I
	`id`:	Public ordinary functions

M
	`make-pool`:	Public ordinary functions
	`map`:	Public ordinary functions

P
	`pack`:	Private ordinary functions

S
	`store`:	Private ordinary functions

U
	`unpack`:	Private ordinary functions

V
	`version`:	Public ordinary functions

Jump to:	% ( A C F G I M P S U V

A.3 Variables

Jump to:	+ C F S

	Index Entry	Section

+
	`+id-bits+`:	Private constants
	`+id-mask+`:	Private constants
	`+version-bits+`:	Private constants
	`+version-mask+`:	Private constants

C
	`Constant, +id-bits+`:	Private constants
	`Constant, +id-mask+`:	Private constants
	`Constant, +version-bits+`:	Private constants
	`Constant, +version-mask+`:	Private constants
	`count`:	Private structures

F
	`free-head`:	Private structures

S
	`Slot, count`:	Private structures
	`Slot, free-head`:	Private structures
	`Slot, store`:	Private structures
	`store`:	Private structures

Jump to:	+ C F S

A.4 Data types

Jump to:	F I P S

	Index Entry	Section

F
	`File, identifier-pool.asd`:	The identifier-pool/identifier-pool․asd file
	`File, identifier-pool.lisp`:	The identifier-pool/identifier-pool․lisp file
	`File, package.lisp`:	The identifier-pool/package․lisp file

I
	`identifier-pool`:	The identifier-pool system
	`identifier-pool`:	The identifier-pool package
	`identifier-pool.asd`:	The identifier-pool/identifier-pool․asd file
	`identifier-pool.lisp`:	The identifier-pool/identifier-pool․lisp file

P
	`Package, identifier-pool`:	The identifier-pool package
	`package.lisp`:	The identifier-pool/package․lisp file
	`pool`:	Private structures

S
	`Structure, pool`:	Private structures
	`System, identifier-pool`:	The identifier-pool system

Jump to:	F I P S

The identifier-pool Reference Manual

The identifier-pool Reference Manual

Table of Contents

1 Introduction

identifier-pool

Overview

Install

License

2 Systems

2.1 identifier-pool

3 Files

3.1 Lisp

3.1.1 identifier-pool/identifier-pool.asd

3.1.2 identifier-pool/package.lisp

3.1.3 identifier-pool/identifier-pool.lisp

4 Packages

4.1 identifier-pool

5 Definitions

5.1 Public Interface

5.1.1 Ordinary functions

5.2 Internals

5.2.1 Constants

5.2.2 Ordinary functions

5.2.3 Structures

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types

2.1 `identifier-pool`

3.1.1 `identifier-pool/identifier-pool.asd`

3.1.2 `identifier-pool/package.lisp`

3.1.3 `identifier-pool/identifier-pool.lisp`

4.1 `identifier-pool`