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