granicus.if.org Git - postgresql/blob - src/backend/utils/misc/README

   1 $PostgreSQL: pgsql/src/backend/utils/misc/README,v 1.10 2008/03/20 17:55:15 momjian Exp $
   2
   3 Guc Implementation Notes
   4 ========================
   5
   6 The GUC (Grand Unified Configuration) module implements configuration
   7 variables of multiple types (currently boolean, enum, 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
  15 Each variable known to GUC can optionally have an assign_hook and/or
  16 a show_hook to provide customized behavior.  Assign hooks are used to
  17 perform validity checking on variable values (above and beyond what
  18 GUC can do).  They are also used to update any derived state that needs
  19 to change when a GUC variable is set.  Show hooks are used to modify
  20 the default SHOW display for a variable.
  21
  22 If an assign_hook is provided, it points to a function of the signature
  23         bool assign_hook(newvalue, bool doit, GucSource source)
  24 where the type of "newvalue" matches the kind of variable.  This function
  25 is called immediately before actually setting the variable's value (so it
  26 can look at the actual variable to determine the old value).  If the
  27 function returns "true" then the assignment is completed; if it returns
  28 "false" then newvalue is considered invalid and the assignment is not
  29 performed.  If "doit" is false then the function should simply check
  30 validity of newvalue and not change any derived state.  The "source" parameter
  31 indicates where the new value came from.  If it is >= PGC_S_INTERACTIVE,
  32 then we are performing an interactive assignment (e.g., a SET command), and
  33 ereport(ERROR) is safe to do.  But when source < PGC_S_INTERACTIVE, we are
  34 reading a non-interactive option source, such as postgresql.conf.  In this
  35 case the assign_hook should *not* ereport but should just return false if it
  36 doesn't like the newvalue.
  37
  38 If an assign_hook returns false then guc.c will report a generic "invalid
  39 value for option FOO" error message.  If you feel the need to provide a more
  40 specific error message, ereport() it using "GUC_complaint_elevel(source)"
  41 as the error level.  Note that this might return either ERROR or a lower level
  42 such as LOG, so the ereport call might or might not return.  If it does
  43 return, return false out of the assign_hook.
  44
  45 For string variables, the signature for assign hooks is a bit different:
  46         const char *assign_hook(const char *newvalue,
  47                                 bool doit,
  48                                 GucSource source)
  49 The meanings of the parameters are the same as for the other types of GUC
  50 variables, but the return value is handled differently:
  51         NULL --- assignment fails (like returning false for other datatypes)
  52         newvalue --- assignment succeeds, assign the newvalue as-is
  53         malloc'd (not palloc'd!!!) string --- assign that value instead
  54 The third choice is allowed in case the assign_hook wants to return a
  55 "canonical" version of the new value.  For example, the assign_hook for
  56 datestyle always returns a string that includes both output and input
  57 datestyle options, although the input might have specified only one.
  58
  59 Note that a string variable's assign_hook will NEVER be called with a NULL
  60 value for newvalue, since there would be no way to distinguish success
  61 and failure returns.  If the boot_val or reset_val for a string variable
  62 is NULL, it will just be assigned without calling the assign_hook.
  63 Therefore, a NULL boot_val should never be used in combination with an
  64 assign_hook that has side-effects, as the side-effects wouldn't happen
  65 during a RESET that re-institutes the boot-time setting.
  66
  67 If a show_hook is provided, it points to a function of the signature
  68         const char *show_hook(void)
  69 This hook allows variable-specific computation of the value displayed
  70 by SHOW.
  71
  72
  73 Saving/Restoring Guc Variable Values
  74 ------------------------------------
  75
  76 Prior values of configuration variables must be remembered in order to deal
  77 with several special cases: RESET (a/k/a SET TO DEFAULT), rollback of SET
  78 on transaction abort, rollback of SET LOCAL at transaction end (either
  79 commit or abort), and save/restore around a function that has a SET option.
  80 RESET is defined as selecting the value that would be effective had there
  81 never been any SET commands in the current session.
  82
  83 To handle these cases we must keep track of many distinct values for each
  84 variable.  The primary values are:
  85
  86 * actual variable contents      always the current effective value
  87
  88 * reset_val                     the value to use for RESET
  89
  90 (Each GUC entry also has a boot_val which is the wired-in default value.
  91 This is assigned to the reset_val and the actual variable during
  92 InitializeGUCOptions().  The boot_val is also consulted to restore the
  93 correct reset_val if SIGHUP processing discovers that a variable formerly
  94 specified in postgresql.conf is no longer set there.)
  95
  96 In addition to the primary values, there is a stack of former effective
  97 values that might need to be restored in future.  Stacking and unstacking
  98 is controlled by the GUC "nest level", which is zero when outside any
  99 transaction, one at top transaction level, and incremented for each
 100 open subtransaction or function call with a SET option.  A stack entry
 101 is made whenever a GUC variable is first modified at a given nesting level.
 102 (Note: the reset_val need not be stacked because it is only changed by
 103 non-transactional operations.)
 104
 105 A stack entry has a state, a prior value of the GUC variable, a remembered
 106 source of that prior value, and depending on the state may also have a
 107 "masked" value.  The masked value is needed when SET followed by SET LOCAL
 108 occur at the same nest level: the SET's value is masked but must be
 109 remembered to restore after transaction commit.
 110
 111 During initialization we set the actual value and reset_val based on
 112 whichever non-interactive source has the highest priority.  They will
 113 have the same value.
 114
 115 The possible transactional operations on a GUC value are:
 116
 117 Entry to a function with a SET option:
 118
 119         Push a stack entry with the prior variable value and state SAVE,
 120         then set the variable.
 121
 122 Plain SET command:
 123
 124         If no stack entry of current level:
 125                 Push new stack entry w/prior value and state SET
 126         else if stack entry's state is SAVE, SET, or LOCAL:
 127                 change stack state to SET, don't change saved value
 128                 (here we are forgetting effects of prior set action)
 129         else (entry must have state SET+LOCAL):
 130                 discard its masked value, change state to SET
 131                 (here we are forgetting effects of prior SET and SET LOCAL)
 132         Now set new value.
 133
 134 SET LOCAL command:
 135
 136         If no stack entry of current level:
 137                 Push new stack entry w/prior value and state LOCAL
 138         else if stack entry's state is SAVE or LOCAL or SET+LOCAL:
 139                 no change to stack entry
 140                 (in SAVE case, SET LOCAL will be forgotten at func exit)
 141         else (entry must have state SET):
 142                 put current active into its masked slot, set state SET+LOCAL
 143         Now set new value.
 144
 145 Transaction or subtransaction abort:
 146
 147         Pop stack entries, restoring prior value, until top < subxact depth
 148
 149 Transaction or subtransaction commit (incl. successful function exit):
 150
 151         While stack entry level >= subxact depth
 152
 153                 if entry's state is SAVE:
 154                         pop, restoring prior value
 155                 else if level is 1 and entry's state is SET+LOCAL:
 156                         pop, restoring *masked* value
 157                 else if level is 1 and entry's state is SET:
 158                         pop, discarding old value
 159                 else if level is 1 and entry's state is LOCAL:
 160                         pop, restoring prior value
 161                 else if there is no entry of exactly level N-1:
 162                         decrement entry's level, no other state change
 163                 else
 164                         merge entries of level N-1 and N as specified below
 165
 166 The merged entry will have level N-1 and prior = older prior, so easiest
 167 to keep older entry and free newer.  There are 12 possibilities since
 168 we already handled level N state = SAVE:
 169
 170 N-1             N
 171
 172 SAVE            SET             discard top prior, set state SET
 173 SAVE            LOCAL           discard top prior, no change to stack entry
 174 SAVE            SET+LOCAL       discard top prior, copy masked, state S+L
 175
 176 SET             SET             discard top prior, no change to stack entry
 177 SET             LOCAL           copy top prior to masked, state S+L
 178 SET             SET+LOCAL       discard top prior, copy masked, state S+L
 179
 180 LOCAL           SET             discard top prior, set state SET
 181 LOCAL           LOCAL           discard top prior, no change to stack entry
 182 LOCAL           SET+LOCAL       discard top prior, copy masked, state S+L
 183
 184 SET+LOCAL       SET             discard top prior and second masked, state SET
 185 SET+LOCAL       LOCAL           discard top prior, no change to stack entry
 186 SET+LOCAL       SET+LOCAL       discard top prior, copy masked, state S+L
 187
 188
 189 RESET is executed like a SET, but using the reset_val as the desired new
 190 value.  (We do not provide a RESET LOCAL command, but SET LOCAL TO DEFAULT
 191 has the same behavior that RESET LOCAL would.)  The source associated with
 192 the reset_val also becomes associated with the actual value.
 193
 194 If SIGHUP is received, the GUC code rereads the postgresql.conf
 195 configuration file (this does not happen in the signal handler, but at
 196 next return to main loop; note that it can be executed while within a
 197 transaction).  New values from postgresql.conf are assigned to actual
 198 variable, reset_val, and stacked actual values, but only if each of
 199 these has a current source priority <= PGC_S_FILE.  (It is thus possible
 200 for reset_val to track the config-file setting even if there is
 201 currently a different interactive value of the actual variable.)
 202
 203 The assign_hook and show_hook routines work only with the actual variable,
 204 and are not directly aware of the additional values maintained by GUC.
 205 This is not a problem for normal usage, since we can assign first to the
 206 actual variable and then (if that succeeds) to the additional values as
 207 needed.  However, for SIGHUP rereads we may not want to assign to the
 208 actual variable.  Our procedure in that case is to call the assign_hook
 209 with doit = false so that the value is validated, but no derived state is
 210 changed.
 211
 212
 213 String Memory Handling
 214 ----------------------
 215
 216 String option values are allocated with strdup, not with the
 217 pstrdup/palloc mechanisms.  We would need to keep them in a permanent
 218 context anyway, and strdup gives us more control over handling
 219 out-of-memory failures.
 220
 221 We allow a string variable's actual value, reset_val, boot_val, and stacked
 222 values to point at the same storage.  This makes it slightly harder to free
 223 space (we must test whether a value to be freed isn't equal to any of the
 224 other pointers in the GUC entry or associated stack items).  The main
 225 advantage is that we never need to strdup during transaction commit/abort,
 226 so cannot cause an out-of-memory failure there.