]> Sergey Matveev's repositories - public-inbox.git/blob - Documentation/technical/memory.txt
lei: no Perl FileHandle for `undef' w/ ECONNRESET
[public-inbox.git] / Documentation / technical / memory.txt
1 semi-automatic memory management in public-inbox
2 ------------------------------------------------
3
4 The majority of public-inbox is implemented in Perl 5, a
5 language and interpreter not particularly known for being
6 memory-efficient.
7
8 We strive to keep processes small to improve locality, allow
9 the kernel to cache more files, and to be a good neighbor to
10 other processes running on the machine.  Taking advantage of
11 automatic reference counting (ARC) in Perl allows us
12 deterministically release memory back to the heap.
13
14 We start with a simple data model with few circular
15 references.  This both eases human understanding and reduces
16 the likelyhood of bugs.
17
18 Knowing the relative sizes and quantities of our data
19 structures, we limit the scope of allocations as much as
20 possible and keep large allocations shortest-lived.  This
21 minimizes both the cognitive overhead on humans in addition
22 to reducing memory pressure on the machine.
23
24 Short-lived non-immortal closures (aka "anonymous subs") are
25 avoided in long-running daemons unless required for
26 compatibility with PSGI.  Closures are memory-intensive and
27 may make allocation lifetimes less obvious to humans.  They
28 are also the source of memory leaks in older versions of
29 Perl, including 5.16.3 found in enterprise distros.
30
31 We also use Perl's `delete' and `undef' built-ins to drop
32 reference counts sooner than scope allows.  These functions
33 are required to break the few reference cycles we have that
34 would otherwise lead to leaks.
35
36 Of note, `undef' may be used in two ways:
37
38 1. to free(3) the underlying buffer:
39
40         undef $scalar;
41
42 2. to reset a buffer but reduce realloc(3) on subsequent growth:
43
44         $scalar = "";           # useful when repeated appending
45         $scalar = undef;        # usually not needed
46
47 In the future, our internal data model will be further
48 flattened and simplified to reduce the overhead imposed by
49 small objects.  Large allocations may also be avoided by
50 optionally using Inline::C.