Thread: custom guc vars

Is there a readme somewhere on how modules are supposed to use custom 
GUC variables? If there is I have missed it.

cheers

andrew

[2005-05-01 18:38] Andrew Dunstan said:
| 
| Is there a readme somewhere on how modules are supposed to use custom 
| GUC variables? If there is I have missed it.
 I don't think there is any documentation for this, but here's a
simple overview.

cheers.Brent

=== postgresql.conf ===
 custom_variable_classes = 'mymodule, anothermodule' mymodule.integer = 10 mymodule.double = 5.5 mymodule.string =
'somestring' mymodule.bool = true anothermodule.whatever = 'some string' anothermodule.other = false
 


=== moduleConfig.c ===
 #include <utils/guc.h>
 int anIntVar; char* aStringVar; double aDoubleVar; bool aBoolVar;
 void setCustomVars() {   DefineCustomIntegerVariable(       "mymodule.integer",       "A custom integer guc var",
NULL,       &anIntVar,       PGC_USERSET,       NULL,NULL);
 
   DefineCustomStringVariable(       "mymodule.string",       "A custom string guc var",       NULL,       &aStringVar,
     PGC_USERSET,       NULL,NULL);
 
   DefineCustomRealVariable(       "mymodule.double",       "A custom double guc var",       NULL,       &aDoubleVar,
   PGC_USERSET,       NULL,NULL);
 
   DefineCustomBoolVariable(       "mymodule.bool",       "A custom bool guc var",       NULL,       &aBoolVar,
PGC_USERSET,      NULL,NULL); }
 

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
onfunction 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