Re: custom guc vars

Andrew Dunstan wrote:
>
> Is there a readme somewhere on how modules are supposed to use custom
> GUC variables? If there is I have missed it.
>
> cheers
>
I don't think there is but here's an attempt.

The set of variables that PostgreSQL will recognize is well defined and
an attempt to extend this set will yield an error, hence the need for a
separate namespace.

The custom_variable_classes will introduce new namespaces where
arbitrary configuration parameters can be added. In addition, this new
concept also defines a way to check the consistency of those variables
so that misspelled or non-existent variables can be detected by the
designated module once it is loaded.

Since modules can be loaded on demand long after the parsing of the
configuration settings, some additional complexity exists. Initially
PostgreSQL will allow all settings and treat everything as PGC_USERSET
and placeholder variables. It's not until a module is loaded and define
those variables that their placeholder status is promoted to a valid
variable.

Example:
Here's an excerpt from the initialization code of PL/Java

DefineCustomIntVariable(
"pljava.statement_cache_size",
"Size of the prepared statement MRU cache",
NULL,
&statementCacheSize,
0, 512,
PGC_USERSET,
NULL, NULL);

DefineCustomBoolVariable(
"pljava.release_lingering_savepoints",
"If true, lingering savepoints will be released on function exit. If
false, the will be rolled back",
NULL,
&pljavaReleaseLingeringSavepoints,
PGC_USERSET,
NULL, NULL);

EmitWarningsOnPlaceholders("pljava");

The first call defines "pljava.statement_cache_size" as an integer
variable ranging from 0 to 512 (not possible in 8.0.0 and 8.0.1 since
there was a bug in the definition, the signature of the definers for int
and real was corrected in 8.0.2). The second defines a boolean variable.

The third call, EmitWarningsOnPlaceholders("pljava") deserves a special
mention. This call will assert that no "pljava.<something>" has been
defined that has not been perused by a DefineCustom<xxx>Variable call.
So if someone for instance misspelled and used
"pljava.release_lingring_savepoints", there would be a warning that this
custom variable is not recognized since a placeholder starting with the
"pljava" prefix still has not been promoted.

You see 3 parameters passed as NULL in the above. The first is an
optional pointer to a "long description". The last two are function
pointers that will allow you to add a special "assign hook" and a "show
hook" function.

For more info on the details, I'm afraid you need to consult the source
code at present.

Kind regards,
Thomas Hallgren