OpenMPI  0.1.1
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  */
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  */
172  orte_iof_base_init_fn_t init;
176  orte_iof_base_finalize_fn_t finalize;
178 };
179 
182 ORTE_DECLSPEC extern orte_iof_base_module_t orte_iof;
183 
185  mca_base_component_t iof_version;
186  mca_base_component_data_t iof_data;
187 };
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 */
Common type for all MCA components.
Definition: mca.h:250
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
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
Definition: types.h:146
Definition: iof.h:184
Top-level interface for all MCA components.
int(* orte_iof_base_ft_event_fn_t)(int state)
FT Event Notification.
Definition: iof.h:166
Meta data for MCA v2.0.0 components.
Definition: mca.h:309
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
Checkpoint and Restart Service (CRS) Interface.
IOF module.
Definition: iof.h:171