mca/base/pmix_mca_base_component_repository.h

0001 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
0002 /*
0003  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
0004  *                         University Research and Technology
0005  *                         Corporation.  All rights reserved.
0006  * Copyright (c) 2004-2005 The University of Tennessee and The University
0007  *                         of Tennessee Research Foundation.  All rights
0008  *                         reserved.
0009  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
0010  *                         University of Stuttgart.  All rights reserved.
0011  * Copyright (c) 2004-2005 The Regents of the University of California.
0012  *                         All rights reserved.
0013  * Copyright (c) 2015      Cisco Systems, Inc.  All rights reserved.
0014  * Copyright (c) 2015      Los Alamos National Security, LLC. All rights
0015  *                         reserved.
0016  * Copyright (c) 2016-2020 Intel, Inc.  All rights reserved.
0017  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0018  * $COPYRIGHT$
0019  *
0020  * Additional copyrights may follow
0021  *
0022  * $HEADER$
0023  */
0024
0025 /**
0026  * @file pmix_mca_base_component_repository.h
0027  *
0028  * This file provide the external interface to our base component
0029  * module.  Most of the components that depend on it, will use the
0030  * retain_component() function to increase the reference count on a
0031  * particular component (as opposed to the retain() function, which is
0032  * internal to the pmix/mca/base).  But it's convenient to have all
0033  * the functions exported from one header file rather than to separate
0034  * retain_component() and retain() into two separate header files
0035  * (i.e., have a separate header file just for retain()).
0036  */
0037
0038 #ifndef PMIX_MCA_BASE_COMPONENT_REPOSITORY_H
0039 #define PMIX_MCA_BASE_COMPONENT_REPOSITORY_H
0040
0041 #include "src/include/pmix_config.h"
0042
0043 #include "src/mca/pdl/base/base.h"
0044 #include "src/mca/pdl/pdl.h"
0045
0046 BEGIN_C_DECLS
0047 struct pmix_mca_base_component_repository_item_t {
0048     pmix_list_item_t super;
0049
0050     char *ri_project;
0051     char ri_type[PMIX_MCA_BASE_MAX_TYPE_NAME_LEN + 1];
0052     char ri_name[PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN + 1];
0053
0054     char *ri_path;
0055     char *ri_base;
0056
0057     pmix_pdl_handle_t *ri_dlhandle;
0058     const pmix_mca_base_component_t *ri_component_struct;
0059
0060     int ri_refcnt;
0061 };
0062 typedef struct pmix_mca_base_component_repository_item_t pmix_mca_base_component_repository_item_t;
0063
0064 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_repository_item_t);
0065
0066 /*
0067  * Structure to track information about why a component failed to load.
0068  */
0069 struct pmix_mca_base_failed_component_t {
0070     pmix_list_item_t super;
0071     pmix_mca_base_component_repository_item_t *comp;
0072     char *error_msg;
0073 };
0074 typedef struct pmix_mca_base_failed_component_t pmix_mca_base_failed_component_t;
0075 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_failed_component_t);
0076
0077 /**
0078  * @brief initialize the component repository
0079  *
0080  * This function must be called before any frameworks are registered or
0081  * opened. It is responsible for setting up the repository of dynamically
0082  * loaded components. The initial search path is taken from the
0083  * pmix_mca_base_component_path MCA parameter. pmix_mca_base_open () is a
0084  * prerequisite call as it registers the pmix_mca_base_component_path parameter.
0085  */
0086 PMIX_EXPORT int pmix_mca_base_component_repository_init(void);
0087
0088 /**
0089  * @brief add search path for dynamically loaded components
0090  *
0091  * @param[in] path        delimited list of search paths to add
0092  */
0093 PMIX_EXPORT int pmix_mca_base_component_repository_add(const char *project,
0094                                                        const char *path);
0095
0096 /**
0097  * @brief return the list of components that match a given framework
0098  *
0099  * @param[in]  framework  framework to match
0100  * @param[out] framework_components components that match this framework
0101  *
0102  * The list returned in {framework_components} is owned by the component
0103  * repository and CAN NOT be modified by the caller.
0104  */
0105 PMIX_EXPORT int
0106 pmix_mca_base_component_repository_get_components(pmix_mca_base_framework_t *framework,
0107                                                   pmix_list_t **framework_components);
0108
0109 /**
0110  * @brief finalize the mca component repository
0111  */
0112 PMIX_EXPORT void pmix_mca_base_component_repository_finalize(void);
0113
0114 /**
0115  * @brief open the repository item and add it to the framework's component
0116  * list
0117  *
0118  * @param[in] framework   framework that matches the component
0119  * @param[in] ri          dynamic component to open
0120  */
0121 PMIX_EXPORT int
0122 pmix_mca_base_component_repository_open(pmix_mca_base_framework_t *framework,
0123                                         pmix_mca_base_component_repository_item_t *ri);
0124
0125 /**
0126  * @brief Reduce the reference count of a component and dlclose it if necessary
0127  */
0128 PMIX_EXPORT void
0129 pmix_mca_base_component_repository_release(const pmix_mca_base_component_t *component);
0130
0131 /**
0132  * @brief Increase the reference count of a component
0133  *
0134  * Each component repository item starts with a reference count of 0. This ensures that
0135  * when a framework closes it's components the repository items are all correctly
0136  * dlclosed. This function can be used to prevent the dlclose if a component is needed
0137  * after its framework has closed the associated component. Users of this function
0138  * should call pmix_mca_base_component_repository_release() once they are finished with the
0139  * component.
0140  *
0141  * @note all components are automatically unloaded by the
0142  * pmix_mca_base_component_repository_finalize() call.
0143  */
0144 PMIX_EXPORT int pmix_mca_base_component_repository_retain_component(const char *type,
0145                                                                     const char *name);
0146
0147 END_C_DECLS
0148
0149 #endif /* MCA_BASE_COMPONENT_REPOSITORY_H */