1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */ 2 /* 3 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana 4 * University Research and Technology 5 * Corporation. All rights reserved. 6 * Copyright (c) 2004-2005 The University of Tennessee and The University 7 * of Tennessee Research Foundation. All rights 8 * reserved. 9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart, 10 * University of Stuttgart. All rights reserved. 11 * Copyright (c) 2004-2005 The Regents of the University of California. 12 * All rights reserved. 13 * Copyright (c) 2015 Cisco Systems, Inc. All rights reserved. 14 * Copyright (c) 2015 Los Alamos National Security, LLC. All rights 15 * reserved. 16 * Copyright (c) 2016-2017 Intel, Inc. All rights reserved. 17 * $COPYRIGHT$ 18 * 19 * Additional copyrights may follow 20 * 21 * $HEADER$ 22 */ 23 24 /** 25 * @file pmix_mca_base_component_repository.h 26 * 27 * This file provide the external interface to our base component 28 * module. Most of the components that depend on it, will use the 29 * retain_component() function to increase the reference count on a 30 * particular component (as opposed to the retain() function, which is 31 * internal to the pmix/mca/base). But it's convenient to have all 32 * the functions exported from one header file rather than to separate 33 * retain_component() and retain() into two separate header files 34 * (i.e., have a separate header file just for retain()). 35 */ 36 37 #ifndef PMIX_MCA_BASE_COMPONENT_REPOSITORY_H 38 #define PMIX_MCA_BASE_COMPONENT_REPOSITORY_H 39 40 #include <src/include/pmix_config.h> 41 42 #include "src/mca/pdl/pdl.h" 43 #include "src/mca/pdl/base/base.h" 44 45 BEGIN_C_DECLS 46 struct pmix_mca_base_component_repository_item_t { 47 pmix_list_item_t super; 48 49 char ri_type[PMIX_MCA_BASE_MAX_TYPE_NAME_LEN + 1]; 50 char ri_name[PMIX_MCA_BASE_MAX_COMPONENT_NAME_LEN + 1]; 51 52 char *ri_path; 53 char *ri_base; 54 55 pmix_pdl_handle_t *ri_dlhandle; 56 const pmix_mca_base_component_t *ri_component_struct; 57 58 int ri_refcnt; 59 }; 60 typedef struct pmix_mca_base_component_repository_item_t pmix_mca_base_component_repository_item_t; 61 62 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_component_repository_item_t); 63 64 /* 65 * Structure to track information about why a component failed to load. 66 */ 67 struct pmix_mca_base_failed_component_t { 68 pmix_list_item_t super; 69 pmix_mca_base_component_repository_item_t *comp; 70 char *error_msg; 71 }; 72 typedef struct pmix_mca_base_failed_component_t pmix_mca_base_failed_component_t; 73 PMIX_EXPORT PMIX_CLASS_DECLARATION(pmix_mca_base_failed_component_t); 74 75 /** 76 * @brief initialize the component repository 77 * 78 * This function must be called before any frameworks are registered or 79 * opened. It is responsible for setting up the repository of dynamically 80 * loaded components. The initial search path is taken from the 81 * pmix_mca_base_component_path MCA parameter. pmix_mca_base_open () is a 82 * prerequisite call as it registers the pmix_mca_base_component_path parameter. 83 */ 84 PMIX_EXPORT int pmix_mca_base_component_repository_init(void); 85 86 /** 87 * @brief add search path for dynamically loaded components 88 * 89 * @param[in] path delimited list of search paths to add 90 */ 91 PMIX_EXPORT int pmix_mca_base_component_repository_add(const char *path); 92 93 94 /** 95 * @brief return the list of components that match a given framework 96 * 97 * @param[in] framework framework to match 98 * @param[out] framework_components components that match this framework 99 * 100 * The list returned in {framework_components} is owned by the component 101 * repository and CAN NOT be modified by the caller. 102 */ 103 PMIX_EXPORT int pmix_mca_base_component_repository_get_components(pmix_mca_base_framework_t *framework, 104 pmix_list_t **framework_components); 105 106 /** 107 * @brief finalize the mca component repository 108 */ 109 PMIX_EXPORT void pmix_mca_base_component_repository_finalize(void); 110 111 /** 112 * @brief open the repository item and add it to the framework's component 113 * list 114 * 115 * @param[in] framework framework that matches the component 116 * @param[in] ri dynamic component to open 117 */ 118 PMIX_EXPORT int pmix_mca_base_component_repository_open(pmix_mca_base_framework_t *framework, 119 pmix_mca_base_component_repository_item_t *ri); 120 121 122 /** 123 * @brief Reduce the reference count of a component and dlclose it if necessary 124 */ 125 PMIX_EXPORT void pmix_mca_base_component_repository_release(const pmix_mca_base_component_t *component); 126 127 /** 128 * @brief Increase the reference count of a component 129 * 130 * Each component repository item starts with a reference count of 0. This ensures that 131 * when a framework closes it's components the repository items are all correctly 132 * dlclosed. This function can be used to prevent the dlclose if a component is needed 133 * after its framework has closed the associated component. Users of this function 134 * should call pmix_mca_base_component_repository_release() once they are finished with the 135 * component. 136 * 137 * @note all components are automatically unloaded by the 138 * pmix_mca_base_component_repository_finalize() call. 139 */ 140 PMIX_EXPORT int pmix_mca_base_component_repository_retain_component(const char *type, const char *name); 141 142 END_C_DECLS 143 144 #endif /* MCA_BASE_COMPONENT_REPOSITORY_H */