OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

iof.h
Go to the documentation of this file.
1 /*
2 * Copyright (c) 2004-2007 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-2008 Cisco Systems, Inc. All rights reserved.
13 * $COPYRIGHT$
14 *
15 * Additional copyrights may follow
16 *
17 * $HEADER$
18 */
19 /**
20 * @file
21 *
22 * I/O Forwarding Service
23 * The I/O forwarding service (IOF) is used to connect stdin, stdout, and
24 * stderr file descriptor streams from MPI processes to the user
25 *
26 * The design is fairly simple: when a proc is spawned, the IOF establishes
27 * connections between its stdin, stdout, and stderr to a
28 * corresponding IOF stream. In addition, the IOF designates a separate
29 * stream for passing OMPI/ORTE internal diagnostic/help output to mpirun.
30 * This is done specifically to separate such output from the user's
31 * stdout/err - basically, it allows us to present it to the user in
32 * a separate format for easier recognition. Data read from a source
33 * on any stream (e.g., printed to stdout by the proc) is relayed
34 * by the local daemon to the other end of the stream - i.e., stdin
35 * is relayed to the local proc, while stdout/err is relayed to mpirun.
36 * Thus, the eventual result is to connect ALL streams to/from
37 * the application process and mpirun.
38 *
39 * Note: By default, data read from stdin is forwarded -only- to rank=0.
40 * Stdin for all other procs is tied to "/dev/null".
41 *
42 * External tools can "pull" copies of stdout/err and
43 * the diagnostic stream from mpirun for any process. In this case,
44 * mpirun will send a copy of the output to the "pulling" process. Note that external tools
45 * cannot "push" something into stdin unless the user specifically directed
46 * that stdin remain open, nor under any conditions "pull" a copy of the
47 * stdin being sent to rank=0.
48 *
49 * Tools can exploit either of two mechanisms for this purpose:
50 *
51 * (a) call orte_init themselves and utilize the ORTE tool comm
52 * library to access the IOF. This also provides access to
53 * other tool library functions - e.g., to order that a job
54 * be spawned; or
55 *
56 * (b) fork/exec the "orte-iof" tool and let it serve as the interface
57 * to mpirun. This lets the tool avoid calling orte_init, and means
58 * the tool will not have to compile against the ORTE/OMPI libraries.
59 * However, the orte-iof tool is limited solely to interfacing
60 * stdio and cannot be used for other functions included in
61 * the tool comm library
62 *
63 * Thus, mpirun acts as a "switchyard" for IO, taking input from stdin
64 * and passing it to rank=0 of the job, and taking stdout/err/diag from all
65 * ranks and passing it to its own stdout/err/diag plus any "pull"
66 * requestors.
67 *
68 * Streams are identified by ORTE process name (to include wildcards,
69 * such as "all processes in ORTE job X") and tag. There are
70 * currently only 4 allowed predefined tags:
71 *
72 * - ORTE_IOF_STDIN (value 0)
73 * - ORTE_IOF_STDOUT (value 1)
74 * - ORTE_IOF_STDERR (value 2)
75 * - ORTE_IOF_INTERNAL (value 3): for "internal" messages
76 * from the infrastructure, just to differentiate them from user job
77 * stdout/stderr
78 *
79 * Note that since streams are identified by ORTE process name, the
80 * caller has no idea whether the stream is on the local node or a
81 * remote node -- it's just a stream.
82 *
83 * IOF components are selected on a "one of many" basis, meaning that
84 * only one IOF component will be selected for a given process.
85 * Details for the various components are given in their source code
86 * bases.
87 *
88 * Each IOF component must support the following API:
89 *
90 * push: Tie a local file descriptor (*not* a stream!) to the stdin
91 * of the specified process. If the user has not specified that stdin
92 * of the specified process is to remain open, this will return an error.
93 *
94 * pull: Tie a local file descriptor (*not* a stream!) to a stream.
95 * Subsequent input that appears via the stream will
96 * automatically be sent to the target file descriptor until the
97 * stream is "closed" or an EOF is received on the local file descriptor.
98 * Valid source values include ORTE_IOF_STDOUT, ORTE_IOF_STDERR, and
99 * ORTE_IOF_INTERNAL
100 *
101 * close: Closes a stream, flushing any pending data down it and
102 * terminating any "push/pull" connections against it. Unclear yet
103 * if this needs to be blocking, or can be done non-blocking.
104 *
105 * flush: Block until all pending data on all open streams has been
106 * written down local file descriptors and/or completed sending across
107 * the OOB to remote process targets.
108 *
109 */
110
111 #ifndef ORTE_IOF_H
112 #define ORTE_IOF_H
113
114 #include "orte_config.h"
115 #include "orte/types.h"
116
117 #include "opal/mca/mca.h"
118
119 #include "opal/mca/crs/crs.h"
120 #include "opal/mca/crs/base/base.h"
121
122
123 #include "iof_types.h"
124
125 BEGIN_C_DECLS
126
127 /* Initialize the selected module */
128 typedef int (*orte_iof_base_init_fn_t)(void);
129
130 /**
131 * Explicitly push data from the specified input file descriptor to
132 * the stdin of the indicated peer(s). The provided peer name can
133 * include wildcard values.
134 *
135 * @param peer Name of target peer(s)
136 * @param fd Local file descriptor for input.
137 */
138 typedef int (*orte_iof_base_push_fn_t)(const orte_process_name_t* peer,
139 orte_iof_tag_t src_tag, int fd);
140
141 /**
142 * Explicitly pull data from the specified set of SOURCE peers and
143 * dump to the indicated output file descriptor. Any fragments that
144 * arrive on the stream will automatically be written down the fd.
145 *
146 * @param peer Name used to qualify set of origin peers.
147 * @param source_tag Indicates the output streams to be forwarded
148 * @param fd Local file descriptor for output.
149 */
150 typedef int (*orte_iof_base_pull_fn_t)(const orte_process_name_t* peer,
151 orte_iof_tag_t source_tag,
152 int fd);
153
154 /**
155 * Close the specified iof stream(s) from the indicated peer(s)
156 */
157 typedef int (*orte_iof_base_close_fn_t)(const orte_process_name_t* peer,
158 orte_iof_tag_t source_tag);
159
160 /* finalize the selected module */
161 typedef int (*orte_iof_base_finalize_fn_t)(void);
162
163 /**
164 * FT Event Notification
165 */
166 typedef int (*orte_iof_base_ft_event_fn_t)(int state);
167
168 /**
169 * IOF module.
170 */
171 struct orte_iof_base_module_2_0_0_t {
172 orte_iof_base_init_fn_t init;
173 orte_iof_base_push_fn_t push;
174 orte_iof_base_pull_fn_t pull;
175 orte_iof_base_close_fn_t close;
176 orte_iof_base_finalize_fn_t finalize;
177 orte_iof_base_ft_event_fn_t ft_event;
178 };
179
180 typedef struct orte_iof_base_module_2_0_0_t orte_iof_base_module_2_0_0_t;
181 typedef orte_iof_base_module_2_0_0_t orte_iof_base_module_t;
182 ORTE_DECLSPEC extern orte_iof_base_module_t orte_iof;
183
184 struct orte_iof_base_component_2_0_0_t {
185 mca_base_component_t iof_version;
186 mca_base_component_data_t iof_data;
187 };
188 typedef struct orte_iof_base_component_2_0_0_t orte_iof_base_component_2_0_0_t;
189 typedef struct orte_iof_base_component_2_0_0_t orte_iof_base_component_t;
190
191 END_C_DECLS
192
193 /*
194 * Macro for use in components that are of type iof
195 */
196 #define ORTE_IOF_BASE_VERSION_2_0_0 \
197 MCA_BASE_VERSION_2_0_0, \
198 "iof", 2, 0, 0
199
200 #endif /* ORTE_IOF_H */
mca_base_component_2_0_0_t
Common type for all MCA components.
Definition: mca.h:250
orte_iof_base_pull_fn_t
int(* orte_iof_base_pull_fn_t)(const orte_process_name_t *peer, orte_iof_tag_t source_tag, int fd)
Explicitly pull data from the specified set of SOURCE peers and dump to the indicated output file des...
Definition: iof.h:150
orte_iof_base_push_fn_t
int(* orte_iof_base_push_fn_t)(const orte_process_name_t *peer, orte_iof_tag_t src_tag, int fd)
Explicitly push data from the specified input file descriptor to the stdin of the indicated peer(s)...
Definition: iof.h:138
iof_types.h
orte_process_name_t
Definition: types.h:146
orte_iof_base_component_2_0_0_t
Definition: iof.h:184
mca.h
Top-level interface for all MCA components.
types.h
orte_iof_base_ft_event_fn_t
int(* orte_iof_base_ft_event_fn_t)(int state)
FT Event Notification.
Definition: iof.h:166
mca_base_component_data_2_0_0_t
Meta data for MCA v2.0.0 components.
Definition: mca.h:309
orte_iof_base_close_fn_t
int(* orte_iof_base_close_fn_t)(const orte_process_name_t *peer, orte_iof_tag_t source_tag)
Close the specified iof stream(s) from the indicated peer(s)
Definition: iof.h:157
crs.h
Checkpoint and Restart Service (CRS) Interface.
orte_iof_base_module_2_0_0_t
IOF module.
Definition: iof.h:171