← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to src/backend/utils/misc/README

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/backend/utils/misc/README
 
1
$PostgreSQL: pgsql/src/backend/utils/misc/README,v 1.5 2004-07-01 00:51:24 tgl Exp $
 
2
 
 
3
 
 
4
GUC IMPLEMENTATION NOTES
 
5
 
 
6
The GUC (Grand Unified Configuration) module implements configuration
 
7
variables of multiple types (currently boolean, int, float, and string).
 
8
Variable settings can come from various places, with a priority ordering
 
9
determining which setting is used.
 
10
 
 
11
 
 
12
PER-VARIABLE HOOKS
 
13
 
 
14
Each variable known to GUC can optionally have an assign_hook and/or
 
15
a show_hook to provide customized behavior.  Assign hooks are used to
 
16
perform validity checking on variable values (above and beyond what
 
17
GUC can do).  They are also used to update any derived state that needs
 
18
to change when a GUC variable is set.  Show hooks are used to modify
 
19
the default SHOW display for a variable.
 
20
 
 
21
If an assign_hook is provided, it points to a function of the signature
 
22
        bool assign_hook(newvalue, bool doit, GucSource source)
 
23
where the type of "newvalue" matches the kind of variable.  This function
 
24
is called immediately before actually setting the variable's value (so it
 
25
can look at the actual variable to determine the old value).  If the
 
26
function returns "true" then the assignment is completed; if it returns
 
27
"false" then newvalue is considered invalid and the assignment is not
 
28
performed.  If "doit" is false then the function should simply check
 
29
validity of newvalue and not change any derived state.  The "source" parameter
 
30
indicates where the new value came from.  If it is >= PGC_S_INTERACTIVE,
 
31
then we are performing an interactive assignment (e.g., a SET command).
 
32
In such cases it is okay for the assign_hook to raise an error via ereport().
 
33
If the function returns false for an interactive assignment then guc.c will
 
34
report a generic "invalid value" error message.  (An internal ereport() in
 
35
an assign_hook is only needed if you want to generate a specialized error
 
36
message.)  But when source < PGC_S_INTERACTIVE, we are reading a
 
37
non-interactive option source, such as postgresql.conf.  In this case the
 
38
assign_hook should *not* ereport but should just return false if it doesn't
 
39
like the newvalue.  (An ereport(LOG) call would be acceptable if you feel a
 
40
need for a custom complaint in this situation.)
 
41
 
 
42
For string variables, the signature for assign hooks is a bit different:
 
43
        const char *assign_hook(const char *newvalue,
 
44
                                bool doit,
 
45
                                GucSource source)
 
46
The meanings of the parameters are the same as for the other types of GUC
 
47
variables, but the return value is handled differently:
 
48
        NULL --- assignment fails (like returning false for other datatypes)
 
49
        newvalue --- assignment succeeds, assign the newvalue as-is
 
50
        malloc'd (not palloc'd!!!) string --- assign that value instead
 
51
The third choice is allowed in case the assign_hook wants to return a
 
52
"canonical" version of the new value.  For example, the assign_hook for
 
53
datestyle always returns a string that includes both output and input
 
54
datestyle options, although the input might have specified only one.
 
55
 
 
56
If a show_hook is provided, it points to a function of the signature
 
57
        const char *show_hook(void)
 
58
This hook allows variable-specific computation of the value displayed
 
59
by SHOW.
 
60
 
 
61
 
 
62
SAVING/RESTORING GUC VARIABLE VALUES
 
63
 
 
64
Prior values of configuration variables must be remembered in order to
 
65
deal with three special cases: RESET (a/k/a SET TO DEFAULT), rollback of
 
66
SET on transaction abort, and rollback of SET LOCAL at transaction end
 
67
(either commit or abort).  RESET is defined as selecting the value that
 
68
would be effective had there never been any SET commands in the current
 
69
session.
 
70
 
 
71
To handle these cases we must keep track of many distinct values for each
 
72
variable.  The primary values are:
 
73
 
 
74
* actual variable contents      always the current effective value
 
75
 
 
76
* reset_value                   the value to use for RESET
 
77
 
 
78
* tentative_value               the uncommitted result of SET
 
79
 
 
80
The reason we need a tentative_value separate from the actual value is
 
81
that when a transaction does SET followed by SET LOCAL, the actual value
 
82
will now be the LOCAL value, but we want to remember the prior SET so that
 
83
that value is restored at transaction commit.
 
84
 
 
85
In addition, for each level of transaction (possibly nested) we have to
 
86
remember the transaction-entry-time actual and tentative values, in case
 
87
we need to restore them at transaction end.  (The RESET value is essentially
 
88
non-transactional, so it doesn't have to be stacked.)  For efficiency these
 
89
stack entries are not constructed until/unless the variable is actually SET
 
90
within a particular transaction.
 
91
 
 
92
During initialization we set the actual value and reset_value based on
 
93
whichever non-interactive source has the highest priority.  They will
 
94
have the same value.  The tentative_value is not meaningful at this point.
 
95
 
 
96
A SET command starts by stacking the existing actual and tentative values
 
97
if this hasn't already been done within the current transaction.  Then:
 
98
 
 
99
A SET LOCAL command sets the actual variable (and nothing else).  At
 
100
transaction end, the stacked values are used to restore the GUC entry
 
101
to its pre-transaction state.
 
102
 
 
103
A SET (or SET SESSION) command sets the actual variable, and if no error,
 
104
then sets the tentative_value.  If the transaction commits, the
 
105
tentative_value is assigned again to the actual variable (which could by
 
106
now be different, if the SET was followed by SET LOCAL).  If the
 
107
transaction aborts, the stacked values are used to restore the GUC entry
 
108
to its pre-transaction state.
 
109
 
 
110
In the case of SET within nested subtransactions, at each commit the
 
111
tentative_value propagates out to the next transaction level.  It will
 
112
be thrown away at abort of any level, or after exiting the top transaction.
 
113
 
 
114
RESET is executed like a SET, but using the reset_value as the desired new
 
115
value.  (We do not provide a RESET LOCAL command, but SET LOCAL TO DEFAULT
 
116
has the same behavior that RESET LOCAL would.)  The source associated with
 
117
the reset_value also becomes associated with the actual and tentative values.
 
118
 
 
119
If SIGHUP is received, the GUC code rereads the postgresql.conf
 
120
configuration file (this does not happen in the signal handler, but at
 
121
next return to main loop; note that it can be executed while within a
 
122
transaction).  New values from postgresql.conf are assigned to actual
 
123
variable, reset_value, and stacked actual values, but only if each of
 
124
these has a current source priority <= PGC_S_FILE.  (It is thus possible
 
125
for reset_value to track the config-file setting even if there is
 
126
currently a different interactive value of the actual variable.)
 
127
 
 
128
Note that tentative_value is unused and undefined except between a SET
 
129
command and the end of the transaction.  Also notice that we must track
 
130
the source associated with each one of the values.
 
131
 
 
132
The assign_hook and show_hook routines work only with the actual variable,
 
133
and are not directly aware of the additional values maintained by GUC.
 
134
This is not a problem for normal usage, since we can assign first to the
 
135
actual variable and then (if that succeeds) to the additional values as
 
136
needed.  However, for SIGHUP rereads we may not want to assign to the
 
137
actual variable.  Our procedure in that case is to call the assign_hook
 
138
with doit = false so that the value is validated, but no derived state is
 
139
changed.
 
140
 
 
141
 
 
142
STRING MEMORY HANDLING
 
143
 
 
144
String option values are allocated with strdup, not with the
 
145
pstrdup/palloc mechanisms.  We would need to keep them in a permanent
 
146
context anyway, and strdup gives us more control over handling
 
147
out-of-memory failures.
 
148
 
 
149
We allow a string variable's actual value, reset_val, tentative_val, and
 
150
stacked copies of same to point at the same storage.  This makes it
 
151
slightly harder to free space (must test whether a value to be freed isn't
 
152
equal to any of the other pointers in the GUC entry or associated stack
 
153
items).  The main advantage is that we never need to strdup during
 
154
transaction commit/abort, so cannot cause an out-of-memory failure there.