OpenMPI  0.1.1
base.h
1 /*
2  * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2006 The University of Tennessee and The University
6  * of Tennessee Research Foundation. All rights
7  * reserved.
8  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
9  * University of Stuttgart. All rights reserved.
10  * Copyright (c) 2004-2005 The Regents of the University of California.
11  * All rights reserved.
12  * Copyright (c) 2007-2011 Cisco Systems, Inc. All rights reserved.
13  * Copyright (c) 2010-2011 Los Alamos National Security, LLC.
14  * All rights reserved.
15  * $COPYRIGHT$
16  *
17  * Additional copyrights may follow
18  *
19  * $HEADER$
20  */
21 
22 #ifndef OPAL_SHMEM_BASE_H
23 #define OPAL_SHMEM_BASE_H
24 
25 #include "opal_config.h"
26 
27 #include "opal/mca/shmem/shmem.h"
28 
29 BEGIN_C_DECLS
30 
31 /* ////////////////////////////////////////////////////////////////////////// */
32 /* Public API for the shmem framework */
33 /* ////////////////////////////////////////////////////////////////////////// */
34 OPAL_DECLSPEC int
35 opal_shmem_segment_create(opal_shmem_ds_t *ds_buf,
36  const char *file_name,
37  size_t size);
38 
39 OPAL_DECLSPEC int
40 opal_shmem_ds_copy(const opal_shmem_ds_t *from,
41  opal_shmem_ds_t *to);
42 
43 OPAL_DECLSPEC void *
44 opal_shmem_segment_attach(opal_shmem_ds_t *ds_buf);
45 
46 OPAL_DECLSPEC int
47 opal_shmem_segment_detach(opal_shmem_ds_t *ds_buf);
48 
49 OPAL_DECLSPEC int
50 opal_shmem_unlink(opal_shmem_ds_t *ds_buf);
51 /* ////////////////////////////////////////////////////////////////////////// */
52 /* End Public API for the shmem framework */
53 /* ////////////////////////////////////////////////////////////////////////// */
54 
55 /*
56  * Global functions for MCA overall shmem open and close
57  */
58 
59 /**
60  * Register MCA params for the shmem base.
61  *
62  * @retval OPAL_SUCCESS Upon success
63  *
64  * This function is invoked by opal_shmem_base_register_params(). It registers
65  * some shmem-wide MCA parameters.
66  */
67 OPAL_DECLSPEC int
68 opal_shmem_base_register_params(void);
69 
70 /**
71  * Performs a run-time query across all available shmem components. Similar to
72  * mca_base_select, but take into consideration environment hints provided by
73  * orte.
74  *
75  * see: orte/mca/odls/base/odls_base_default_fns.c
76  */
77 OPAL_DECLSPEC int
78 opal_shmem_base_runtime_query(mca_base_module_t **best_module,
79  mca_base_component_t **best_component);
80 
81 /**
82  * returns the name of the best, runnable shmem component. the caller is
83  * responsible for freeing returned resources.
84  *
85  * @retval name of best component. NULL if no component is found.
86  *
87  * see: orte/mca/odls/base/odls_base_default_fns.c
88  */
89 OPAL_DECLSPEC char *
90 opal_shmem_base_best_runnable_component_name(void);
91 
92 /**
93  * Initialize the shmem MCA framework
94  *
95  * @retval OPAL_SUCCESS Upon success
96  * @retval OPAL_ERROR Upon failure
97  *
98  * This must be the first function invoked in the shmem MCA
99  * framework. It initializes the shmem MCA framework, finds
100  * and opens shmem components, etc.
101  *
102  * This function is invoked during opal_init().
103  *
104  * This function fills in the internal global variable
105  * opal_shmem_base_components_opened, which is a list of all
106  * shmem components that were successfully opened. This
107  * variable should \em only be used by other shmem base
108  * functions -- it is not considered a public interface member --
109  * and is only mentioned here for completeness.
110  */
111 OPAL_DECLSPEC int
112 opal_shmem_base_open(void);
113 
114 /**
115  * Select an available component.
116  *
117  * @return OPAL_SUCCESS Upon success.
118  * @return OPAL_NOT_FOUND If no component can be selected.
119  * @return OPAL_ERROR Upon other failure.
120  *
121  * This function invokes the selection process for shmem components,
122  * which works as follows:
123  *
124  * - If the \em shmem MCA parameter is not specified, the
125  * selection set is all available shmem components.
126  * - If the \em shmem MCA parameter is specified, the
127  * selection set is just that component.
128  * - All components in the selection set are queried to see if
129  * they want to run. All components that want to run are ranked
130  * by their priority and the highest priority component is
131  * selected. All non-selected components have their "close"
132  * function invoked to let them know that they were not selected.
133  * - The selected component will have its "init" function invoked to
134  * let it know that it was selected.
135  *
136  * If we fall through this entire process and no component is
137  * selected, then return OPAL_NOT_FOUND (this is not a fatal
138  * error).
139  *
140  * At the end of this process, we'll either have a single
141  * component that is selected and initialized, or no component was
142  * selected. If no component was selected, subsequent invocation
143  * of the shmem wrapper functions will return an error.
144  */
145 OPAL_DECLSPEC int
146 opal_shmem_base_select(void);
147 
148 /**
149  * Shut down the shmem MCA framework.
150  *
151  * @retval OPAL_SUCCESS Always
152  *
153  * This function shuts down everything in the shmem MCA
154  * framework, and is called during opal_finalize().
155  *
156  * It must be the last function invoked on the shmem MCA
157  * framework.
158  */
159 OPAL_DECLSPEC int
160 opal_shmem_base_close(void);
161 
162 /**
163  * Indication of whether a component was successfully selected or
164  * not
165  */
166 OPAL_DECLSPEC extern bool opal_shmem_base_selected;
167 
168 /**
169  * Global component struct for the selected component
170  */
171 OPAL_DECLSPEC extern const opal_shmem_base_component_2_0_0_t
172 *opal_shmem_base_component;
173 
174 /**
175  * Global module struct for the selected module
176  */
177 OPAL_DECLSPEC extern const opal_shmem_base_module_2_0_0_t
178 *opal_shmem_base_module;
179 
180 /**
181  * Indicator as to whether the list of opened shmem components
182  * is valid or not.
183  */
184 OPAL_DECLSPEC extern bool opal_shmem_base_components_opened_valid;
185 
186 /**
187  * List of all opened components; created when the shmem
188  * framework is initialized and destroyed when we reduce the list
189  * to all available shmem components.
190  */
191 OPAL_DECLSPEC extern opal_list_t opal_shmem_base_components_opened;
192 
193 /**
194  * Debugging output stream
195  */
196 OPAL_DECLSPEC extern int opal_shmem_base_output;
197 
198 END_C_DECLS
199 
200 #endif /* OPAL_BASE_SHMEM_H */
Common type for all MCA components.
Definition: mca.h:250
Common type for all MCA modules.
Definition: mca.h:100
structure for shmem modules
Definition: shmem.h:163
Definition: shmem.h:62
Definition: shmem_types.h:107
Definition: opal_list.h:147
shmem (shared memory backing facility) framework component interface definitions. ...