1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
.ds EP \fIGAWK: Effective AWK Programming\fP
.ds PM \fIPersistent Memory gawk User Manual\fP
.TH PM-GAWK 1 "Nov 17 2022" "Free Software Foundation" "Utility Commands"
.SH NAME
persistent memory gawk \- persistent data and functions
.SH SYNOPSIS
.ft CW
.nf
truncate -s \f(CIsize\fP heap.pma
export GAWK_PERSIST_FILE=heap.pma
gawk .\^.\^.
.sp
truncate -s \f(CIsize\fP heap.pma
GAWK_PERSIST_FILE=heap.pma gawk .\^.\^.
.sp
truncate -s \f(CIsize\fP heap.pma
alias pm='GAWK_PERSIST_FILE=heap.pma'
pm gawk .\^.\^. # succinct
.sp
unset GAWK_PERSIST_FILE # disable persistence
.sp
export GAWK_PERSIST_FILE=other_heap.pma # change heap
.sp
rm heap.pma # delete heap
.fi
.ft R
.SH DESCRIPTION
.PP
.I Gawk
5.2 and later supports a persistent memory feature that
can store script-defined variables and functions in a
file for later use. The feature, called
.IR pm-gawk ,
is described in \*(EP and in \*(PM.
.PP
.I pm-gawk
is activated by passing to
.I gawk
the name of an initially empty
(all-zero-bytes)
.IR "heap file" ,
via the environment variable
\f(CWGAWK_PERSIST_FILE\fP.
.I pm-gawk
retains script-defined variables and functions in the heap file for
use in subsequent
.I gawk
invocations.
.PP
.I pm-gawk
offers at least two advantages compared with the existing \f(CWrwarray\fP
extension: it offers constant-time (``O(1) time'') access to individual
elements of persistent associative arrays, and it can store script-defined
functions in addition to variables.
.SH EXAMPLES
.PP
Demonstrate persistent variables:
.sp .5
.RS
.nf
.ft CW
$ \f(CBtruncate -s 1G heap.pma\fP # create heap file
$ \f(CBexport GAWK_PERSIST_FILE=heap.pma\fP # "ambient" env var
$ \f(CBgawk 'BEGIN { print ++i }'\fP
1
$ \f(CBgawk 'BEGIN { print ++i }'\fP
2
$ \f(CBgawk 'BEGIN { print ++i }'\fP
3
.ft R
.fi
.RE
.PP
To pass the environment variable on per-command basis:
.sp .5
.RS
.nf
.ft CW
$ \f(CBunset GAWK_PERSIST_FILE\fP
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
4
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
5
$ \f(CBGAWK_PERSIST_FILE=heap.pma gawk 'BEGIN { print ++i }'\fP
6
.ft R
.fi
.RE
.PP
To reduce visual clutter of per-command environment variable passing:
.sp .5
.RS
.nf
.ft CW
$ \f(CBalias pm='GAWK_PERSIST_FILE=heap.pma'\fP
$ \f(CBpm gawk 'BEGIN { print ++i }'\fP
7
$ \f(CBpm gawk 'BEGIN { print ++i }'\fP
8
.ft R
.fi
.RE
.PP
To refrain from activating persistence:
.sp .5
.RS
.nf
.ft CW
$ \f(CBunset GAWK_PERSIST_FILE\fP
$ \f(CBgawk 'BEGIN { print ++i }'\fP
1
$ \f(CBgawk 'BEGIN { print ++i }'\fP
1
.ft R
.fi
.RE
.PP
To permanently ``forget'' the contents of the heap file:
.sp .5
.RS
.nf
.ft CW
$ \f(CBrm heap.pma\fP
.ft R
.fi
.RE
.PP
.SH ENVIRONMENT VARIABLES
.PP
\f(CWGAWK_PERSIST_FILE\fP contains the name of a heap file where
script-defined variables and functions are stored. If this environment
variable is not visible to
.IR gawk ,
the
persistence feature is not activated and
.I gawk
behaves in
its traditional manner.
.SH VERSION INFORMATION
.PP
Persistent memory
.I gawk
was first released in
.I gawk
5.2.
.SH AUTHORS
Arnold Robbins, the maintainer of
.IR gawk ,
implemented
.I pm-gawk
using a persistent memory allocator (pma) provided by
Terence Kelly. An earlier proof-of-concept prototype
of persistent
.I gawk
was developed by Haris Volos, Zi Fan
Tan, and Jianan Li using a fork of the official
.I gawk
sources.
.SH CAVEATS
The GNU/Linux CIFS filesystem is known to cause problems
for the persistent memory allocator. Do not use a backing file
on such a filesystem with
.IR pm-gawk .
.SH BUG REPORTS
Follow the procedures in \*(EP and in \*(PM.
For suspected
bugs related to persistence (as opposed to other
non-persistence-related
.I gawk
bugs) please also send
e-mail to Terence Kelly at one or more of these addresses:
\f(CWtpkelly@acm.org\fP,
\f(CWtpkelly@eecs.umich.edu\fP,
or
\f(CWtpkelly@cs.princeton.edu\fP.
.SH SEE ALSO
.IR gawk (1),
\*(EP,
and
\*(PM.
The two manuals should be available in the Info subsystem
if Info installed on your system.
.PP
See \f(CWhttps://web.eecs.umich.edu/~tpkelly/pma/\fP for
the latest source code and manual.
.SH COPYING PERMISSIONS
Copyright \(co 2022
Terence Kelly.
.PP
Permission is granted to make and distribute verbatim copies of
this manual page provided the copyright notice and this permission
notice are preserved on all copies.
.ig
Permission is granted to process this file through troff and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual page).
..
.PP
Permission is granted to copy and distribute modified versions of this
manual page under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
.PP
Permission is granted to copy and distribute translations of this
manual page into another language, under the above conditions for
modified versions, except that this permission notice may be stated in
a translation approved by the Foundation.
|
