Documentation
¶
Overview ¶
Package uid provides a thread-safe, lock-free pool of unprivileged UIDs for per-MicroVM isolation. Each Firecracker process is assigned a unique UID/GID from the pool, ensuring DAC (Discretionary Access Control) isolation between concurrent tenants on the same host.
Design rationale:
- A buffered channel is used as the backing store. Channel send/receive is handled by the Go runtime via lock-free fast-paths in most cases, making Checkout a sub-microsecond operation with zero mutex overhead on the hot path.
- Checkout is a non-blocking select so callers get an immediate ErrPoolExhausted rather than blocking indefinitely when the pool is empty.
- Return validates the returned UID is in-range to catch bugs early rather than silently corrupting the pool.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrPoolExhausted = errors.New("uid pool exhausted: all UIDs are currently leased to active VMs")
ErrPoolExhausted is returned by Checkout when no UIDs are available.
Functions ¶
This section is empty.
Types ¶
type Pool ¶
type Pool struct {
// contains filtered or unexported fields
}
Pool is a thread-safe, lock-free pool of unprivileged UIDs. It must be created via NewPool; the zero value is not usable.
The pool assigns UIDs from a contiguous range [start, start+size). Both Checkout and Return are safe for concurrent use from multiple goroutines.
func NewPool ¶
NewPool creates a Pool covering UIDs in [start, start+size).
Constraints:
- start must be > 0 (UID 0 is root; never acceptable as a jailer UID).
- size must be >= 1.
The pool is pre-filled in ascending order so the first Checkout always returns start, making behaviour deterministic and easy to reason about in tests.
func (*Pool) Available ¶
Available returns a snapshot of the number of UIDs currently available for checkout. This is a point-in-time observation; the true count may change immediately after the call.
func (*Pool) Checkout ¶
Checkout leases the next available UID from the pool.
This is a non-blocking operation: if the pool is empty it returns ErrPoolExhausted immediately rather than blocking the caller. The caller must call Return when the UID is no longer needed (i.e., after the associated Firecracker process has fully exited and all resources have been cleaned up).
Source Files