• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..07-May-2022-

.gitignoreH A D08-Nov-202112 21

MakefileH A D08-Nov-20211,016 3614

READMEH A D08-Nov-202113.6 KiB296235

backend_random.cH A D08-Nov-20213.3 KiB15984

check_gucH A D08-Nov-20212.5 KiB7937

guc-file.cH A D08-Nov-202182.3 KiB3,2312,078

guc-file.lH A D08-Nov-202132.4 KiB1,227801

guc.cH A D08-Nov-2021278.7 KiB10,8998,094

help_config.cH A D08-Nov-20213.2 KiB13984

pg_config.cH A D08-Nov-20212.9 KiB10354

pg_controldata.cH A D08-Nov-202110.5 KiB350248

pg_rusage.cH A D08-Nov-20211.8 KiB7440

postgresql.conf.sampleH A D03-May-202223.5 KiB695569

ps_status.cH A D08-Nov-202110.4 KiB420234

queryenvironment.cH A D08-Nov-20213.5 KiB14571

rls.cH A D08-Nov-20215.3 KiB16869

sampling.cH A D08-Nov-20217.8 KiB293158

superuser.cH A D08-Nov-20212.7 KiB10950

timeout.cH A D08-Nov-202117.4 KiB671292

tzparser.cH A D08-Nov-202112.1 KiB477296

README

1src/backend/utils/misc/README
2
3GUC Implementation Notes
4========================
5
6The GUC (Grand Unified Configuration) module implements configuration
7variables of multiple types (currently boolean, enum, int, real, and string).
8Variable settings can come from various places, with a priority ordering
9determining which setting is used.
10
11
12Per-Variable Hooks
13------------------
14
15Each variable known to GUC can optionally have a check_hook, an
16assign_hook, and/or a show_hook to provide customized behavior.
17Check hooks are used to perform validity checking on variable values
18(above and beyond what GUC can do), to compute derived settings when
19nontrivial work is needed to do that, and optionally to "canonicalize"
20user-supplied values.  Assign hooks are used to update any derived state
21that needs to change when a GUC variable is set.  Show hooks are used to
22modify the default SHOW display for a variable.
23
24
25If a check_hook is provided, it points to a function of the signature
26	bool check_hook(datatype *newvalue, void **extra, GucSource source)
27The "newvalue" argument is of type bool *, int *, double *, or char **
28for bool, int/enum, real, or string variables respectively.  The check
29function should validate the proposed new value, and return true if it is
30OK or false if not.  The function can optionally do a few other things:
31
32* When rejecting a bad proposed value, it may be useful to append some
33additional information to the generic "invalid value for parameter FOO"
34complaint that guc.c will emit.  To do that, call
35	void GUC_check_errdetail(const char *format, ...)
36where the format string and additional arguments follow the rules for
37errdetail() arguments.  The resulting string will be emitted as the
38DETAIL line of guc.c's error report, so it should follow the message style
39guidelines for DETAIL messages.  There is also
40	void GUC_check_errhint(const char *format, ...)
41which can be used in the same way to append a HINT message.
42Occasionally it may even be appropriate to override guc.c's generic primary
43message or error code, which can be done with
44	void GUC_check_errcode(int sqlerrcode)
45	void GUC_check_errmsg(const char *format, ...)
46In general, check_hooks should avoid throwing errors directly if possible,
47though this may be impractical to avoid for some corner cases such as
48out-of-memory.
49
50* Since the newvalue is pass-by-reference, the function can modify it.
51This might be used for example to canonicalize the spelling of a string
52value, round off a buffer size to the nearest supported value, or replace
53a special value such as "-1" with a computed default value.  If the
54function wishes to replace a string value, it must malloc (not palloc)
55the replacement value, and be sure to free() the previous value.
56
57* Derived information, such as the role OID represented by a user name,
58can be stored for use by the assign hook.  To do this, malloc (not palloc)
59storage space for the information, and return its address at *extra.
60guc.c will automatically free() this space when the associated GUC setting
61is no longer of interest.  *extra is initialized to NULL before call, so
62it can be ignored if not needed.
63
64The "source" argument indicates the source of the proposed new value,
65If it is >= PGC_S_INTERACTIVE, then we are performing an interactive
66assignment (e.g., a SET command).  But when source < PGC_S_INTERACTIVE,
67we are reading a non-interactive option source, such as postgresql.conf.
68This is sometimes needed to determine whether a setting should be
69allowed.  The check_hook might also look at the current actual value of
70the variable to determine what is allowed.
71
72Note that check hooks are sometimes called just to validate a value,
73without any intention of actually changing the setting.  Therefore the
74check hook must *not* take any action based on the assumption that an
75assignment will occur.
76
77
78If an assign_hook is provided, it points to a function of the signature
79	void assign_hook(datatype newvalue, void *extra)
80where the type of "newvalue" matches the kind of variable, and "extra"
81is the derived-information pointer returned by the check_hook (always
82NULL if there is no check_hook).  This function is called immediately
83before actually setting the variable's value (so it can look at the actual
84variable to determine the old value, for example to avoid doing work when
85the value isn't really changing).
86
87Note that there is no provision for a failure result code.  assign_hooks
88should never fail except under the most dire circumstances, since a failure
89may for example result in GUC settings not being rolled back properly during
90transaction abort.  In general, try to do anything that could conceivably
91fail in a check_hook instead, and pass along the results in an "extra"
92struct, so that the assign hook has little to do beyond copying the data to
93someplace.  This applies particularly to catalog lookups: any required
94lookups must be done in the check_hook, since the assign_hook may be
95executed during transaction rollback when lookups will be unsafe.
96
97Note that check_hooks are sometimes called outside any transaction, too.
98This happens when processing the wired-in "bootstrap" value, values coming
99from the postmaster command line or environment, or values coming from
100postgresql.conf.  Therefore, any catalog lookups done in a check_hook
101should be guarded with an IsTransactionState() test, and there must be a
102fallback path to allow derived values to be computed during the first
103subsequent use of the GUC setting within a transaction.  A typical
104arrangement is for the catalog values computed by the check_hook and
105installed by the assign_hook to be used only for the remainder of the
106transaction in which the new setting is made.  Each subsequent transaction
107looks up the values afresh on first use.  This arrangement is useful to
108prevent use of stale catalog values, independently of the problem of
109needing to check GUC values outside a transaction.
110
111
112If a show_hook is provided, it points to a function of the signature
113	const char *show_hook(void)
114This hook allows variable-specific computation of the value displayed
115by SHOW (and other SQL features for showing GUC variable values).
116The return value can point to a static buffer, since show functions are
117not used reentrantly.
118
119
120Saving/Restoring GUC Variable Values
121------------------------------------
122
123Prior values of configuration variables must be remembered in order to deal
124with several special cases: RESET (a/k/a SET TO DEFAULT), rollback of SET
125on transaction abort, rollback of SET LOCAL at transaction end (either
126commit or abort), and save/restore around a function that has a SET option.
127RESET is defined as selecting the value that would be effective had there
128never been any SET commands in the current session.
129
130To handle these cases we must keep track of many distinct values for each
131variable.  The primary values are:
132
133* actual variable contents	always the current effective value
134
135* reset_val			the value to use for RESET
136
137(Each GUC entry also has a boot_val which is the wired-in default value.
138This is assigned to the reset_val and the actual variable during
139InitializeGUCOptions().  The boot_val is also consulted to restore the
140correct reset_val if SIGHUP processing discovers that a variable formerly
141specified in postgresql.conf is no longer set there.)
142
143In addition to the primary values, there is a stack of former effective
144values that might need to be restored in future.  Stacking and unstacking
145is controlled by the GUC "nest level", which is zero when outside any
146transaction, one at top transaction level, and incremented for each
147open subtransaction or function call with a SET option.  A stack entry
148is made whenever a GUC variable is first modified at a given nesting level.
149(Note: the reset_val need not be stacked because it is only changed by
150non-transactional operations.)
151
152A stack entry has a state, a prior value of the GUC variable, a remembered
153source of that prior value, and depending on the state may also have a
154"masked" value.  The masked value is needed when SET followed by SET LOCAL
155occur at the same nest level: the SET's value is masked but must be
156remembered to restore after transaction commit.
157
158During initialization we set the actual value and reset_val based on
159whichever non-interactive source has the highest priority.  They will
160have the same value.
161
162The possible transactional operations on a GUC value are:
163
164Entry to a function with a SET option:
165
166	Push a stack entry with the prior variable value and state SAVE,
167	then set the variable.
168
169Plain SET command:
170
171	If no stack entry of current level:
172		Push new stack entry w/prior value and state SET
173	else if stack entry's state is SAVE, SET, or LOCAL:
174		change stack state to SET, don't change saved value
175		(here we are forgetting effects of prior set action)
176	else (entry must have state SET+LOCAL):
177		discard its masked value, change state to SET
178		(here we are forgetting effects of prior SET and SET LOCAL)
179	Now set new value.
180
181SET LOCAL command:
182
183	If no stack entry of current level:
184		Push new stack entry w/prior value and state LOCAL
185	else if stack entry's state is SAVE or LOCAL or SET+LOCAL:
186		no change to stack entry
187		(in SAVE case, SET LOCAL will be forgotten at func exit)
188	else (entry must have state SET):
189		put current active into its masked slot, set state SET+LOCAL
190	Now set new value.
191
192Transaction or subtransaction abort:
193
194	Pop stack entries, restoring prior value, until top < subxact depth
195
196Transaction or subtransaction commit (incl. successful function exit):
197
198	While stack entry level >= subxact depth
199
200		if entry's state is SAVE:
201			pop, restoring prior value
202		else if level is 1 and entry's state is SET+LOCAL:
203			pop, restoring *masked* value
204		else if level is 1 and entry's state is SET:
205			pop, discarding old value
206		else if level is 1 and entry's state is LOCAL:
207			pop, restoring prior value
208		else if there is no entry of exactly level N-1:
209			decrement entry's level, no other state change
210		else
211			merge entries of level N-1 and N as specified below
212
213The merged entry will have level N-1 and prior = older prior, so easiest
214to keep older entry and free newer.  There are 12 possibilities since
215we already handled level N state = SAVE:
216
217N-1		N
218
219SAVE		SET		discard top prior, set state SET
220SAVE		LOCAL		discard top prior, no change to stack entry
221SAVE		SET+LOCAL	discard top prior, copy masked, state S+L
222
223SET		SET		discard top prior, no change to stack entry
224SET		LOCAL		copy top prior to masked, state S+L
225SET		SET+LOCAL	discard top prior, copy masked, state S+L
226
227LOCAL		SET		discard top prior, set state SET
228LOCAL		LOCAL		discard top prior, no change to stack entry
229LOCAL		SET+LOCAL	discard top prior, copy masked, state S+L
230
231SET+LOCAL	SET		discard top prior and second masked, state SET
232SET+LOCAL	LOCAL		discard top prior, no change to stack entry
233SET+LOCAL	SET+LOCAL	discard top prior, copy masked, state S+L
234
235
236RESET is executed like a SET, but using the reset_val as the desired new
237value.  (We do not provide a RESET LOCAL command, but SET LOCAL TO DEFAULT
238has the same behavior that RESET LOCAL would.)  The source associated with
239the reset_val also becomes associated with the actual value.
240
241If SIGHUP is received, the GUC code rereads the postgresql.conf
242configuration file (this does not happen in the signal handler, but at
243next return to main loop; note that it can be executed while within a
244transaction).  New values from postgresql.conf are assigned to actual
245variable, reset_val, and stacked actual values, but only if each of
246these has a current source priority <= PGC_S_FILE.  (It is thus possible
247for reset_val to track the config-file setting even if there is
248currently a different interactive value of the actual variable.)
249
250The check_hook, assign_hook and show_hook routines work only with the
251actual variable, and are not directly aware of the additional values
252maintained by GUC.
253
254
255GUC Memory Handling
256-------------------
257
258String variable values are allocated with malloc/strdup, not with the
259palloc/pstrdup mechanisms.  We would need to keep them in a permanent
260context anyway, and malloc gives us more control over handling
261out-of-memory failures.
262
263We allow a string variable's actual value, reset_val, boot_val, and stacked
264values to point at the same storage.  This makes it slightly harder to free
265space (we must test whether a value to be freed isn't equal to any of the
266other pointers in the GUC entry or associated stack items).  The main
267advantage is that we never need to malloc during transaction commit/abort,
268so cannot cause an out-of-memory failure there.
269
270"Extra" structs returned by check_hook routines are managed in the same
271way as string values.  Note that we support "extra" structs for all types
272of GUC variables, although they are mainly useful with strings.
273
274
275GUC and Null String Variables
276-----------------------------
277
278A GUC string variable can have a boot_val of NULL.  guc.c handles this
279unsurprisingly, assigning the NULL to the underlying C variable.  Any code
280using such a variable, as well as any hook functions for it, must then be
281prepared to deal with a NULL value.
282
283However, it is not possible to assign a NULL value to a GUC string
284variable in any other way: values coming from SET, postgresql.conf, etc,
285might be empty strings, but they'll never be NULL.  And SHOW displays
286a NULL the same as an empty string.  It is therefore not appropriate to
287treat a NULL value as a distinct user-visible setting.  A typical use
288for a NULL boot_val is to denote that a value hasn't yet been set for
289a variable that will receive a real value later in startup.
290
291If it's undesirable for code using the underlying C variable to have to
292worry about NULL values ever, the variable can be given a non-null static
293initializer as well as a non-null boot_val.  guc.c will overwrite the
294static initializer pointer with a copy of the boot_val during
295InitializeGUCOptions, but the variable will never contain a NULL.
296