usr/src/lib/libpool/common/pool_impl.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
  24  * Use is subject to license terms.
  25  */
  26
  27 #ifndef _POOL_IMPL_H
  28 #define _POOL_IMPL_H
  29
  30 #pragma ident   "%Z%%M% %I%     %E% SMI"
  31
  32 #ifdef  __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*
  37  * This file contains the definitions of types and supporting
  38  * functions to implement the libpool generic data manipulation
  39  * facility.
  40  *
  41  * libpool is designed so that the data representation/storage method
  42  * used may be easily replaced without affecting core functionality.
  43  * A libpool configuration is connected to a particular data
  44  * representation/storage "driver" via the pool_connection_t
  45  * type. When a configuration is opened (see pool_conf_open) the
  46  * libpool implementation allocates a specific data manipulation type
  47  * and initialises it. For instance, see pool_xml_connection_alloc.
  48  *
  49  * This function represents a cross-over point and all routines used
  50  * for data representation/storage are controlled by the type of
  51  * allocated connection.
  52  *
  53  * Currently, there are two implemented methods of access. Data may be
  54  * retrieved from the kernel, using the pool_knl_connection_t
  55  * function. This implementation relies on a private interface
  56  * provided by a driver, /dev/pool, and presents data retrieved from
  57  * the kernel via the standard libpool interface. Alternatively, data
  58  * may be retrieved from an XML file, via pool_xml_connection_t, and
  59  * presented through the standard libpool interface. For details of
  60  * these two implementations, see pool_kernel_impl.h and
  61  * pool_xml_impl.h.
  62  *
  63  * In addition to defining a specific connection type for a desired
  64  * data representation/storage medium, several other structures must
  65  * be defined to allow manipulation of configuration elements.
  66  *
  67  * Configuration elements are represented as pool_elem_t instances, or
  68  * as sub-types of this generic type (such as pool_t, which represents
  69  * a pool element) with groups (or sets) of these instances available
  70  * for manipulation via the pool_result_set_t type.
  71  *
  72  * For more information on the implementation of these types, read the
  73  * detailed comments above each structure definition.
  74  */
  75
  76 /*
  77  * The pool_elem_t is used to represent a configuration element.The
  78  * class of the element is stored within the structure along with a
  79  * pointer to the containing configuration and a pointer to the
  80  * element's specific subtype.
  81  *
  82  * The function pointers are initialised when the element is allocated
  83  * to use the specific functions provided by the concrete data
  84  * representation.
  85  *
  86  * The full set of operations that can be performed on an element
  87  * which require special treatment from the data
  88  * representation/storage medium are defined.
  89  */
  90 struct pool_elem {
  91         pool_conf_t *pe_conf;                           /* Configuration */
  92         pool_elem_class_t pe_class;                     /* Element class */
  93         pool_resource_elem_class_t pe_resource_class;   /* Resource class */
  94         pool_component_elem_class_t pe_component_class; /* Component class */
  95         struct pool_elem *pe_pair;                      /* Static pair */
  96         pool_value_class_t (*pe_get_prop)(const pool_elem_t *, const char *,
  97             pool_value_t *);
  98         int (*pe_put_prop)(pool_elem_t *, const char *, const pool_value_t *);
  99         int (*pe_rm_prop)(pool_elem_t *, const char *);
 100         pool_value_t **(*pe_get_props)(const pool_elem_t *, uint_t *);
 101         int (*pe_remove)(pool_elem_t *);
 102         pool_elem_t *(*pe_get_container)(const pool_elem_t *);
 103         int (*pe_set_container)(pool_elem_t *, pool_elem_t *);
 104 };
 105
 106 /*
 107  * libpool performs many operations against a pool_elem_t. This basic
 108  * type is extended to provide specific functionality and type safety
 109  * for each of the different types of element supported by
 110  * libpool. There are four types of element:
 111  * - pool_system_t, represents an entire configuration
 112  * - pool_t, represents a single pool
 113  * - pool_resource_t, represents a single resource
 114  * - pool_component_t, represents a single resource component
 115  *
 116  * pool_system_t is an internal structure, the other structures are
 117  * externally visible and form a major part of the libpool interface.
 118  */
 119 typedef struct pool_system
 120 {
 121         pool_elem_t ps_elem;
 122         void *pe_pad1;
 123         void *pe_pad2;
 124 } pool_system_t;
 125
 126 struct pool
 127 {
 128         pool_elem_t pp_elem;
 129         /*
 130          * Specific to pool_t
 131          */
 132         int (*pp_associate)(pool_t *, const pool_resource_t *);
 133         int (*pp_dissociate)(pool_t *, const pool_resource_t *);
 134 };
 135
 136 struct pool_resource
 137 {
 138         pool_elem_t pr_elem;
 139         /*
 140          * Specific to pool_resource_t
 141          */
 142         int (*pr_is_system)(const pool_resource_t *);
 143         int (*pr_can_associate)(const pool_resource_t *);
 144 };
 145
 146 struct pool_component
 147 {
 148         pool_elem_t pc_elem;
 149         void *pe_pad1;
 150         void *pe_pad2;
 151 };
 152
 153 /*
 154  * The pool_result_set_t is used to represent a collection (set) of
 155  * configuration elements. The configuration to which this result set
 156  * applies is stored along with an indicator as to whether the result
 157  * set is still in use.
 158  *
 159  * The function pointers are initialised when the element is allocated
 160  * to use the specific functions provided by the concrete data
 161  * representation.
 162  *
 163  * The full set of operations that can be performed on an element
 164  * which require special treatment from the data
 165  * representation/storage medium are defined.
 166  */
 167 typedef struct pool_result_set {
 168         pool_conf_t *prs_conf;                          /* Configuration */
 169         int prs_active;                                 /* Query active? */
 170         int prs_index;                                  /* Result Index */
 171         pool_elem_t *(*prs_next)(struct pool_result_set *);
 172         pool_elem_t *(*prs_prev)(struct pool_result_set *);
 173         pool_elem_t *(*prs_first)(struct pool_result_set *);
 174         pool_elem_t *(*prs_last)(struct pool_result_set *);
 175         int (*prs_set_index)(struct pool_result_set *, int);
 176         int (*prs_get_index)(struct pool_result_set *);
 177         int (*prs_close)(struct pool_result_set *);
 178         int (*prs_count)(struct pool_result_set *);
 179 } pool_result_set_t;
 180
 181 /*
 182  * The pool_connection_t is used to represent a connection between a
 183  * libpool configuration and a particular implementation of the
 184  * libpool interface in a specific data representation/storage medium,
 185  * e.g. XML.
 186  *
 187  * The name of the storage medium is stored along with the type of the
 188  * data store.
 189  *
 190  * The function pointers are initialised when the element is allocated
 191  * to use the specific functions provided by the concrete data
 192  * representation.
 193  *
 194  * The full set of operations that can be performed on an element
 195  * which require special treatment from the data
 196  * representation/storage medium are defined.
 197  */
 198 typedef struct pool_connection {
 199         const char *pc_name;                            /* Provider name */
 200         int pc_store_type;                              /* Datastore type */
 201         int pc_oflags;                                  /* Open flags */
 202         int (*pc_close)(pool_conf_t *);
 203         int (*pc_validate)(const pool_conf_t *, pool_valid_level_t);
 204         int (*pc_commit)(pool_conf_t *);
 205         int (*pc_export)(const pool_conf_t *, const char *,
 206             pool_export_format_t);
 207         int (*pc_rollback)(pool_conf_t *);
 208         pool_result_set_t *(*pc_exec_query)(const pool_conf_t *,
 209             const pool_elem_t *, const char *, pool_elem_class_t,
 210             pool_value_t **);
 211         pool_elem_t *(*pc_elem_create)(pool_conf_t *, pool_elem_class_t,
 212             pool_resource_elem_class_t, pool_component_elem_class_t);
 213         int (*pc_remove)(pool_conf_t *);
 214         int (*pc_res_xfer)(pool_resource_t *, pool_resource_t *, uint64_t);
 215         int (*pc_res_xxfer)(pool_resource_t *, pool_resource_t *,
 216             pool_component_t **);
 217         char *(*pc_get_binding)(pool_conf_t *, pid_t);
 218         int (*pc_set_binding)(pool_conf_t *, const char *, idtype_t, id_t);
 219         char *(*pc_get_resource_binding)(pool_conf_t *,
 220             pool_resource_elem_class_t, pid_t);
 221 } pool_connection_t;
 222
 223 /*
 224  * pool_conf represents a resource management configuration. The
 225  * configuration location is stored in the pc_location member with the
 226  * state of the configuration stored in pc_state.
 227  *
 228  * The pc_prov member provides data representation/storage abstraction
 229  * for the configuration since all access to data is performed through
 230  * this member.
 231  */
 232 struct pool_conf {
 233         const char *pc_location;                        /* Location */
 234         pool_connection_t *pc_prov;                     /* Data Provider */
 235         pool_conf_state_t pc_state;                     /* State */
 236 };
 237
 238 /*
 239  * Convert a pool_elem_t to it's appropriate sub-type.
 240  */
 241 extern pool_system_t    *pool_conf_system(const pool_conf_t *);
 242 extern pool_system_t    *pool_elem_system(const pool_elem_t *);
 243 extern pool_t           *pool_elem_pool(const pool_elem_t *);
 244 extern pool_resource_t  *pool_elem_res(const pool_elem_t *);
 245 extern pool_component_t *pool_elem_comp(const pool_elem_t *);
 246
 247 /*
 248  * Convert a pool_system_t to a pool_elem_t.
 249  */
 250 extern pool_elem_t      *pool_system_elem(const pool_system_t *);
 251
 252 /*
 253  * Get/Set an element's "pair" element. A pair element is a temporary
 254  * association at commit between an element in the dynamic
 255  * configuration and an element in the static configuration. This
 256  * relationship is stored in the pe_pair member of the element.
 257  */
 258 extern pool_elem_t      *pool_get_pair(const pool_elem_t *);
 259 extern void             pool_set_pair(pool_elem_t *, pool_elem_t *);
 260
 261 /*
 262  * Result Set Manipulation
 263  */
 264 extern pool_elem_t      *pool_rs_next(pool_result_set_t *);
 265 extern pool_elem_t      *pool_rs_prev(pool_result_set_t *);
 266 extern pool_elem_t      *pool_rs_first(pool_result_set_t *);
 267 extern pool_elem_t      *pool_rs_last(pool_result_set_t *);
 268 extern int              pool_rs_count(pool_result_set_t *);
 269 extern int              pool_rs_get_index(pool_result_set_t *);
 270 extern int              pool_rs_set_index(pool_result_set_t *, int);
 271 extern int              pool_rs_close(pool_result_set_t *);
 272
 273 /*
 274  * General Purpose Query
 275  */
 276 extern pool_result_set_t *pool_exec_query(const pool_conf_t *,
 277     const pool_elem_t *, const char *, pool_elem_class_t, pool_value_t **);
 278
 279 #ifdef  __cplusplus
 280 }
 281 #endif
 282
 283 #endif  /* _POOL_IMPL_H */