Documentation
¶
Overview ¶
Package portalloc provides a central port allocator for Gopherstack services. Services that expose real network endpoints (e.g., ElastiCache, Lambda function URLs) can request a dedicated port from the pool and release it when the resource is deleted.
Index ¶
- Variables
- func AcquireEphemeral() (int, error)
- func AcquireFrom(alloc *Allocator, label string) (int, error)
- func IsListening(addr string) bool
- func ListenTCP(ctx context.Context, port int) (net.Listener, int, error)
- func ReleaseEphemeral(port int)
- func ReleaseTo(alloc *Allocator, port int)
- type Allocator
- func (a *Allocator) Acquire(label string) (int, error)
- func (a *Allocator) Allocated() map[int]string
- func (a *Allocator) Available() int
- func (a *Allocator) IsAllocated(port int) bool
- func (a *Allocator) Release(port int) error
- func (a *Allocator) Reserve(port int, label string) error
- func (a *Allocator) Reserved() map[int]string
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidRange = errors.New("invalid port range: start must be ≥ 1 and end > start")
ErrInvalidRange is returned when the port range is invalid.
var ErrNoPortsAvailable = errors.New("no ports available in range")
ErrNoPortsAvailable is returned when the pool has no free ports.
var ErrPortAlreadyReserved = errors.New("port already reserved or allocated")
ErrPortAlreadyReserved is returned by Reserve when port is already marked used (by a prior Reserve or Acquire call).
var ErrPortNotAllocated = errors.New("port not allocated")
ErrPortNotAllocated is returned when trying to release a port that was not allocated.
Functions ¶
func AcquireEphemeral ¶
AcquireEphemeral probes the OS for a free loopback port and records it process-wide, so no other caller is handed the same number until ReleaseEphemeral.
func AcquireFrom ¶
AcquireFrom takes a port from alloc when non-nil, else a process-unique ephemeral loopback port. Pair with ReleaseTo.
func IsListening ¶
IsListening performs a TCP health check on the given address to detect zombie listeners — ports that are allocated but no longer serving connections. Returns true if a listener is detected.
func ListenTCP ¶
ListenTCP binds ":port" and returns the listener with the port actually bound. Port 0 asks the OS for an ephemeral port, so callers never pre-pick one.
func ReleaseEphemeral ¶
func ReleaseEphemeral(port int)
ReleaseEphemeral makes a port from AcquireEphemeral reusable.
Types ¶
type Allocator ¶
type Allocator struct {
// contains filtered or unexported fields
}
Allocator manages a pool of ports within a configurable range. It is safe for concurrent use.
func New ¶
New creates a new Allocator for the half-open range [start, end). start must be ≥ 1 and end must be > start.
func (*Allocator) Acquire ¶
Acquire returns the next free port in the range and associates it with label. Returns ErrNoPortsAvailable when the pool is exhausted.
func (*Allocator) Allocated ¶
Allocated returns a snapshot of allocated ports and out-of-range reserved fixed ports, with labels.
func (*Allocator) IsAllocated ¶
IsAllocated reports whether port is currently allocated.
func (*Allocator) Release ¶
Release returns a previously allocated port back to the pool. Returns ErrPortNotAllocated if the port was not allocated.
func (*Allocator) Reserve ¶
Reserve permanently marks port as unavailable in the pool, associating it with label, without actually binding anything -- for services that bind a fixed port of their own outside this allocator entirely (e.g. a protocol-conventional default port), so Acquire never hands that same port to a different caller and causes a surprise address-in-use failure later. Intended to be called once at startup, before any Acquire calls.
A port outside [start, end) is not tracked in the pool (Acquire never considers it) but is remembered for reporting via Allocated. Returns ErrPortAlreadyReserved if port is already marked used.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package portalloctest hands tests port allocators over disjoint, probed-free blocks.
|
Package portalloctest hands tests port allocators over disjoint, probed-free blocks. |