List All Resource Pools

The following example lists all resource pools defined in an application's pools pset.

The key points of the example include the following:

• Open the dynamic conf file read-only, PO_RDONLY. pool_query_pools() returns the list of pools in pl and the number of pools in nelem. For each pool, call pool_get_property() to get the pool.name property from the element into the pval value.

• pool_get_property() calls pool_to_elem() to convert the libpool entity to an opaque value. pool_value_get_string() gets the string from the opaque pool value.

conf	= pool_conf_alloc();
pool_conf_open(conf, pool_dynamic_location(), PO_RDONLY);
pl = pool_query_pools(conf, &nelem, NULL);
pval = pool_value_alloc();
for (i = 0; i < nelem; i++) {
    pool_get_property(conf, pool_to_elem(conf, pl[i]), "pool.name", pval);
    pool_value_get_string(pval, &fname);
    printf("%s\n", name);
}
pool_value_free(pval);
free(pl);
pool_conf_close(conf);

Report Pool Statistics for a Given Pool

The following example reports statistics for the designated pool.

The key points for the example include the following:

• pool_query_pool_resources() gets a list of all resources in rl. Because the last argument to pool_query_pool_resources() is NULL, all resources are returned. For each resource, the name, load and size properties are read, and printed.

• The call to strdup() allocates local memory and copies the string returned by get_string(). The call to get_string() returns a pointer that is freed by the next call to get_property(). If the call to strdup() is not included, subsequent references to the string(s) could cause the application to fail with a segmentation fault.

printf("pool %s\n:" pool_name);
pool = pool_get_pool(conf, pool_name);
rl = pool_query_pool_resources(conf, pool, &nelem, NULL);
for (i = 0; i < nelem; i++) {
  pool_get_property(conf, pool_resource_to_elem(conf, rl[i]), "type", pval);
  pool_value_get_string(pval, &type);
  type = strdup(type);
  snprintf(prop_name, 32, "%s.%s", type, "name");
  pool_get_property(conf, pool_resource_to_elem(conf, rl[i]), 
        prop_name, pval);
  pool_value_get_string(val, &res_name);
  res_name = strdup(res_name);
  snprintf(prop_name, 32, "%s.%s", type, "load");
  pool_get_property(conf, pool_resource_to_elem(conf, rl[i]), 
        prop_name, pval);
  pool_value_get_uint64(val, &load);
  snprintf(prop_name, 32, "%s.%s", type, "size");
  pool_get_property(conf, pool_resource_to_elem(conf, rl[i]), 
        prop_name, pval);
  pool_value_get_uint64(val, &size);
  printf("resource %s: size %llu load %llu\n", res_name, size, load);
  free(type);
  free(res_name);
}
free(rl);

Set pool.comment Property and Add New Property

The following example sets the pool.comment property for the pset. The example also creates a new property in pool.newprop.

The key point for the example includes the following:

• In the call to pool_conf_open(), using PO_RDWR on a static configuration file, requires the caller to be root.

• To commit these changes to the pset after running this utility, issue a pooladm -c command. To have the utility commit the changes, call pool_conf_commit() with a nonzero second argument.

pool_set_comment(const char *pool_name, const char *comment)
{
  pool_t *pool;
  pool_elem_t *pool_elem;
  pool_value_t *pval = pool_value_alloc(); 
  pool_conf_t  *conf = pool_conf_alloc();
  /* NOTE: need to be root to use PO_RDWR on static configuration file */
  pool_conf_open(conf, pool_static_location(), PO_RDWR);
  pool = pool_get_pool(conf,  pool_name);
  pool_value_set_string(pval, comment);
  pool_elem = pool_to_elem(conf, pool);
  pool_put_property(conf, pool_elem, "pool.comment", pval);
  printf("pool %s: pool.comment set to %s\n:" pool_name, comment);
  /* Now, create a new property, customized to installation site */
  pool_value_set_string(pval, "New String Property");
  pool_put_property(conf, pool_elem, "pool.newprop", pval);
  pool_conf_commit(conf, 0); /* NOTE: use 0 to ensure only */
                             /* static file gets updated */
  pool_value_free(pval);
  pool_conf_close(conf);
  pool_conf_free(conf);
  /* NOTE: Use "pooladm -c" later, or pool_conf_commit(conf, 1) */
  /* above for changes to the running system */
}

An alternative way of modifying a pool's comment and adding a new pool property is to use poolcfg(1M).

poolcfg -c 'modify pool pool-name (string pool.comment = "cmt-string")'
poolcfg -c 'modify pool pool-name (string pool.newprop = 
                                   "New String Property")'

Programming Issues Associated With Resource Pools

Consider the following issues when writing your application.

• Each site can add its own list of properties to the pools configuration.

  Multiple configurations can be maintained in multiple configuration files. The system administrator can commit different files to reflect changes to the resource consumption at different time slots. These time slots can include different times of the day, week, month, or seasons depending on load conditions.

• Resource sets can be shared between pools, but a pool has only one resource set of a given type. So, the pset_default can be shared between the default and a particular application's database pools.

• Use pool_value_*() interfaces carefully. Keep in mind the memory allocation issues for string pool values. See Report Pool Statistics for a Given Pool.