Documentation
¶
Overview ¶
Package gitlimit is the shared chokepoint for git subprocesses that untrusted input can make expensive (#313, #322): the process-wide admission pool, the per-child heap cap, and their error values. The read API (internal/gitread, ADR-049) and cache maintenance (internal/githttp's commit-graph refresh, ADR-47) both use it, so they share one admission pool instead of each bounding itself. It is a leaf package: gitread imports githttp, so the shared pieces cannot live in gitread.
Index ¶
Constants ¶
const ( // HeavyHeapBytes caps the heap (RLIMIT_DATA, Linux) of a child whose // work grows with history length, tree size, blob size, or output // size. See gitread.HeavyHeapBytes for the measurements. HeavyHeapBytes int64 = 256 << 20 // ReadSlotCount is the size of ReadSlots: requests with JSON // responses that run git, plus admitted maintenance, at once in this // process. ReadSlotCount = 8 // RepoSlotCount is how many slots of a pool one repository may hold. RepoSlotCount = 2 // ReadSlotWait is how long a read request waits for a ReadSlots slot. ReadSlotWait = time.Second // (commit-graph refreshes) may hold at once, so it can never take the // whole pool from reads. MaintenanceShare = 2 )
Variables ¶
var ( // ErrBusy: no admission slot freed up in time; git was not started. ErrBusy = errors.New("git read capacity exhausted") // ErrMemoryLimit: git needed more heap than its cap and was stopped by // its own allocation failure (Linux only). ErrMemoryLimit = errors.New("git exceeded its memory limit") )
var ReadSlots = NewSlots(ReadSlotCount, RepoSlotCount, ReadSlotWait)
ReadSlots is the process-wide pool shared by JSON git reads (the read API's budget middleware) and admitted maintenance.
Functions ¶
func Command ¶
Command returns `git args...`. When maxHeapBytes > 0 it runs git behind /bin/sh, which sets RLIMIT_DATA (`ulimit -d`, KiB) and then execs git, so the limit is in force before git allocates anything and the process id stays git's (context kill and Wait still reach git). An inherited stricter limit is kept. If the limit cannot be read or set, the shell exits 125 and git never runs.
RLIMIT_DATA counts the heap and other private writable mappings, which includes every thread's stack and malloc arena; read-only pack mappings (shared page cache) are not counted.
func HeapFailure ¶
HeapFailure reports whether a git run under a heap cap died of it: git's fatal allocation diagnostics, or, when the cap is hit before or outside git's checked allocators (dynamic loader, libc), a crash by SIGSEGV, SIGBUS, or SIGABRT. SIGKILL (context cancellation or deadline) is not a heap failure.
Only a fatal line that STARTS with a known diagnostic counts: git messages can quote request input (a path named "out of memory"), and such text never forms the start of the line.
func HeapLimitSupported ¶
func HeapLimitSupported() bool
HeapLimitSupported reports whether Run can cap a git child's heap on this platform (RLIMIT_DATA via `ulimit -d`).
func RepoKey ¶
RepoKey is the Slots key of a repository: its canonical RepoID, so every spelling of one repository shares one per-repository quota.
func TryAdmitMaintenance ¶
TryAdmitMaintenance admits one optional maintenance job for the repository key (RepoKey) into ReadSlots without waiting: it needs one of the MaintenanceShare maintenance permits AND one ReadSlots slot within that repository's share, both taken with non-blocking tries (no check-then-act on counts). So at most MaintenanceShare jobs run, reads always keep the rest of the pool, and a repository's maintenance and reads share its per-repository quota. ok=false means skip the job; a caller holding other locks never blocks here. release must be called exactly once when ok.
Types ¶
type Slots ¶
type Slots struct {
// contains filtered or unexported fields
}
Slots is a pool of admission slots. One key (a repository, RepoKey) may hold at most perKey of them, so slow work on one repository cannot take the whole pool from the others. A holder releases exactly the slots it acquired, under the same key.
func NewSlots ¶
NewSlots returns a pool of n slots, at most perKey of them per key. Acquire waits at most wait for a free slot before failing with ErrBusy.
func (*Slots) Acquire ¶
Acquire takes a slot for key, waiting at most the pool's wait (ErrBusy) or until ctx ends (its error).
func (*Slots) TryAcquire ¶
TryAcquire takes a slot for key if one is free right now.