OpenMPI  0.1.1
base.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana
3  * University Research and Technology
4  * Corporation. All rights reserved.
5  * Copyright (c) 2004-2005 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 Los Alamos National Security, LLC. All rights
13  * reserved.
14  * $COPYRIGHT$
15  *
16  * Additional copyrights may follow
17  *
18  * $HEADER$
19  */
20 
21 /**
22  * @file
23  *
24  * RML Framework maintenence interface
25  *
26  * Interface for starting / stopping / controlling the RML framework,
27  * as well as support for modifying RML datatypes.
28  *
29  * @note The only RML datatype exposed to the user is the RML tag.
30  * This will always be an integral value, so the only datatype support
31  * really required is the internal DSS functions for packing /
32  * unpacking / comparing tags. The user should never need to deal
33  * with these.
34  */
35 
36 #ifndef MCA_RML_BASE_H
37 #define MCA_RML_BASE_H
38 
39 #include "orte_config.h"
40 
41 #include "opal/mca/mca.h"
42 #include "orte/mca/rml/rml.h"
43 #include "opal/dss/dss_types.h"
44 
45 BEGIN_C_DECLS
46 
47 
48 /* ******************************************************************** */
49 
50 
51 /**
52  * Open the RML framework
53  *
54  * Open the RML framework. Loads all available RML components and
55  * runs their open functions.
56  *
57  * @retval ORTE_SUCCESS Components successfully loaded
58  * @retval ORTE_ERROR An unknown error occurred
59  */
60 ORTE_DECLSPEC int orte_rml_base_open(void);
61 
62 /**
63  * Select an active RML component
64  *
65  * Select an RML component from the list of frameworks that were
66  * opened during orte_rml_base_open(). The orte_rml_base_select()
67  * function will fill in the orte_rml structure so that all functions
68  * in the interface exist. Note that there are still calling
69  * restrictions at that point (see the documentation for
70  * orte_rml_component_init_fn_t).
71  *
72  * All components that are not selected will be closed during this
73  * call.
74  *
75  * @retval ORTE_SUCCESS Components successfully selected
76  * @retval ORTE_ERROR An unknown error occurred
77  */
78 ORTE_DECLSPEC int orte_rml_base_select(void);
79 
80 
81 /**
82  * Close the RML framework
83  *
84  * Close the RML framework, releasing all resources associated with
85  * the framework interface. Also closes the active component used
86  * during the application.
87  *
88  * @retval ORTE_SUCCESS Framework successfully shut down
89  */
90 ORTE_DECLSPEC int orte_rml_base_close(void);
91 
92 /**
93  * Post receive to get updates regarding contact information
94  *
95  * Post a non-blocking receive (likely during orte_init()) to receive
96  * updated contact information from the HNP when it becomes available.
97  * This should be called in any process that needs such updates, and
98  * the receive will continue to get update callbacks until
99  * orte_rml_base_comm_stop() is called.
100  *
101  * @retval ORTE_SUCCESS Receive successfully started
102  * @retval ORTE_ERROR An unknown error occurred
103  */
104 ORTE_DECLSPEC int orte_rml_base_comm_start(void);
105 
106 
107 /**
108  * Stop receiving contact information updates
109  *
110  * Shut down the receive posted during orte_rml_base_comm_start(),
111  * likely during orte_finalize().
112  *
113  * @retval ORTE_SUCCESS Receive succesffully cancelled.
114  */
115 ORTE_DECLSPEC int orte_rml_base_comm_stop(void);
116 
117 
118 /**
119  * Output stream for RML debugging
120  *
121  * Output stream for the opal_output() code intended for RML output.
122  * It will be have its verbosity set according to the MCA parameter
123  * rml_base_verbose. Useable between call to orte_rml_base_open() and
124  * orte_rml_base_close().
125  */
126 ORTE_DECLSPEC extern int orte_rml_base_output;
127 
128 
129 /**
130  * List of components that are available to the RML
131  *
132  * List of components that are currently available to the RML
133  * framework. Useable between calls to orte_rml_base_open() and
134  * orte_rml_base_close().
135  *
136  * @note This list should not be used by code outside the RML base.
137  */
138 ORTE_DECLSPEC extern opal_list_t orte_rml_base_components;
139 
140 
141 /**
142  * Component structure for the selected RML component
143  *
144  * Component structure pointer for the currently selected RML
145  * component. Useable between calls to orte_rml_base_select() and
146  * orte_rml_base_close().
147  *
148  * @note This pointer should not be used outside the RML base. It is
149  * available outside the RML base only for the F/T component.
150  */
151 ORTE_DECLSPEC extern orte_rml_component_t *orte_rml_component;
152 
153 
154 /*
155  * This is the base priority for a RML wrapper component
156  * If there exists more than one wrapper, then the one with
157  * the lowest priority wins.
158  */
159 #define RML_SELECT_WRAPPER_PRIORITY -128
160 
161 /* null functions */
162 int orte_rml_base_null_send(struct orte_process_name_t* peer,
163  struct iovec *msg,
164  int count,
165  int tag,
166  int flags);
167 int orte_rml_base_null_send_nb(struct orte_process_name_t* peer,
168  struct iovec* msg,
169  int count,
170  orte_rml_tag_t tag,
171  int flags,
172  orte_rml_callback_fn_t cbfunc,
173  void* cbdata);
174 int orte_rml_base_null_send_buffer(struct orte_process_name_t* peer,
175  struct opal_buffer_t* buffer,
176  orte_rml_tag_t tag,
177  int flags);
178 int orte_rml_base_null_send_buffer_nb(struct orte_process_name_t* peer,
179  struct opal_buffer_t* buffer,
180  orte_rml_tag_t tag,
181  int flags,
183  void* cbdata);
184 int orte_rml_base_null_recv(struct orte_process_name_t* peer,
185  struct iovec *msg,
186  int count,
187  orte_rml_tag_t tag,
188  int flags);
189 int orte_rml_base_null_recv_nb(struct orte_process_name_t* peer,
190  struct iovec* msg,
191  int count,
192  orte_rml_tag_t tag,
193  int flags,
194  orte_rml_callback_fn_t cbfunc,
195  void* cbdata);
196 int orte_rml_base_null_recv_buffer(struct orte_process_name_t* peer,
197  struct opal_buffer_t *buf,
198  orte_rml_tag_t tag,
199  int flags);
200 int orte_rml_base_null_recv_buffer_nb(struct orte_process_name_t* peer,
201  orte_rml_tag_t tag,
202  int flags,
204  void* cbdata);
205 int orte_rml_base_null_recv_cancel(orte_process_name_t* peer,
206  orte_rml_tag_t tag);
207 
208 END_C_DECLS
209 
210 #endif /* MCA_RML_BASE_H */
RML component interface.
Definition: rml.h:89
ORTE_DECLSPEC int orte_rml_base_output
Output stream for RML debugging.
Definition: rml_base_components.c:57
Definition: types.h:146
ORTE_DECLSPEC int orte_rml_base_comm_stop(void)
Stop receiving contact information updates.
Definition: rml_base_receive.c:74
ORTE_DECLSPEC orte_rml_component_t * orte_rml_component
Component structure for the selected RML component.
Definition: rml_base_components.c:60
Top-level interface for all MCA components.
void(* orte_rml_callback_fn_t)(int status, struct orte_process_name_t *peer, struct iovec *msg, int count, orte_rml_tag_t tag, void *cbdata)
Funtion prototype for callback from non-blocking iovec send and receive.
Definition: rml.h:123
ORTE_DECLSPEC int orte_rml_base_comm_start(void)
Post receive to get updates regarding contact information.
Definition: rml_base_receive.c:53
BEGIN_C_DECLS ORTE_DECLSPEC int orte_rml_base_open(void)
Open the RML framework.
Definition: rml_base_components.c:89
Runtime Messaging Layer (RML) Communication Interface.
Definition: ompi_uio.h:29
ORTE_DECLSPEC int orte_rml_base_close(void)
Close the RML framework.
Definition: rml_base_components.c:266
Buffer management types.
ORTE_DECLSPEC int orte_rml_base_select(void)
Select an active RML component.
Definition: rml_base_components.c:129
uint32_t orte_rml_tag_t
Message matching tag.
Definition: rml_types.h:220
Definition: opal_list.h:147
void(* orte_rml_buffer_callback_fn_t)(int status, struct orte_process_name_t *peer, struct opal_buffer_t *buffer, orte_rml_tag_t tag, void *cbdata)
Funtion prototype for callback from non-blocking buffer send and receive.
Definition: rml.h:149
Structure for holding a buffer to be used with the RML or OOB subsystems.
Definition: dss_types.h:159
ORTE_DECLSPEC opal_list_t orte_rml_base_components
List of components that are available to the RML.
Definition: rml_base_components.c:59