src/backend/utils/misc/README

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