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 */