1PM-GAWK(1) Utility Commands PM-GAWK(1)
2
6 persistent memory gawk - persistent data and functions
7
9 truncate -s size heap.pma
10 export GAWK_PERSIST_FILE=heap.pma
11 gawk ...
12 truncate -s size heap.pma
14 GAWK_PERSIST_FILE=heap.pma gawk ...
15 truncate -s size heap.pma
17 alias pm='GAWK_PERSIST_FILE=heap.pma'
18 pm gawk ... # succinct
19 unset GAWK_PERSIST_FILE # disable persistence
21 export GAWK_PERSIST_FILE=other_heap.pma # change heap
23 rm heap.pma # delete heap
25
27 Gawk 5.2 and later supports a persistent memory feature that can store
28 script-defined variables and functions in a file for later use. The
29 feature, called pm-gawk, is described in GAWK: Effective AWK Program‐
30 ming and in Persistent Memory gawk User Manual.
31 pm-gawk is activated by passing to gawk the name of an initially empty
33 (all-zero-bytes) heap file, via the environment variable GAWK_PER‐
34 SIST_FILE. pm-gawk retains script-defined variables and functions in
35 the heap file for use in subsequent gawk invocations.
36 pm-gawk offers at least two advantages compared with the existing rwar‐
38 ray extension: it offers constant-time (``O(1) time'') access to indi‐
39 vidual elements of persistent associative arrays, and it can store
40 script-defined functions in addition to variables.
41
43 Demonstrate persistent variables:
44 $ truncate -s 1G heap.pma # create heap file
45 $ export GAWK_PERSIST_FILE=heap.pma # "ambient" env var
46 $ gawk 'BEGIN { print ++i }'
47 1
48 $ gawk 'BEGIN { print ++i }'
49 2
50 $ gawk 'BEGIN { print ++i }'
51 3
52 To pass the environment variable on per-command basis:
54 $ unset GAWK_PERSIST_FILE
55 $ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
56 4
57 $ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
58 5
59 $ GAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'
60 6
61 To reduce visual clutter of per-command environment variable passing:
63 $ alias pm='GAWK_PERSIST_FILE=heap.pma'
64 $ pm gawk 'BEGIN { print ++i }'
65 7
66 $ pm gawk 'BEGIN { print ++i }'
67 8
68 To refrain from activating persistence:
70 $ unset GAWK_PERSIST_FILE
71 $ gawk 'BEGIN { print ++i }'
72 1
73 $ gawk 'BEGIN { print ++i }'
74 1
75 To permanently ``forget'' the contents of the heap file:
77 $ rm heap.pma
78
80 GAWK_PERSIST_FILE contains the name of a heap file where script-defined
81 variables and functions are stored. If this environment variable is
82 not visible to gawk, the persistence feature is not activated and gawk
83 behaves in its traditional manner.
84
86 Persistent memory gawk was first released in gawk 5.2.
87
89 Arnold Robbins, the maintainer of gawk, implemented pm-gawk using a
90 persistent memory allocator (pma) provided by Terence Kelly. An ear‐
91 lier proof-of-concept prototype of persistent gawk was developed by
92 Haris Volos, Zi Fan Tan, and Jianan Li using a fork of the official
93 gawk sources.
94
96 The GNU/Linux CIFS filesystem is known to cause problems for the per‐
97 sistent memory allocator. Do not use a backing file on such a filesys‐
98 tem with pm-gawk.
99
101 Follow the procedures in GAWK: Effective AWK Programming and in Persis‐
102 tent Memory gawk User Manual. For suspected bugs related to persis‐
103 tence (as opposed to other non-persistence-related gawk bugs) please
104 also send e-mail to Terence Kelly at one or more of these addresses:
105 tpkelly@acm.org, tpkelly@eecs.umich.edu, or tpkelly@cs.princeton.edu.
106
108 gawk(1), GAWK: Effective AWK Programming, and Persistent Memory gawk
109 User Manual. The two manuals should be available in the Info subsystem
110 if Info installed on your system.
111 See https://web.eecs.umich.edu/~tpkelly/pma/ for the latest source code
113 and manual.
114
116 Copyright © 2022 Terence Kelly.
117 Permission is granted to make and distribute verbatim copies of this
119 manual page provided the copyright notice and this permission notice
120 are preserved on all copies.
121 Permission is granted to copy and distribute modified versions of this
123 manual page under the conditions for verbatim copying, provided that
124 the entire resulting derived work is distributed under the terms of a
125 permission notice identical to this one.
126 Permission is granted to copy and distribute translations of this man‐
128 ual page into another language, under the above conditions for modified
129 versions, except that this permission notice may be stated in a trans‐
130 lation approved by the Foundation.
131Free Software Foundation Nov 17 2022 PM-GAWK(1)