OpenMPI  0.1.1
output.h File Reference

OPAL output stream facility. More...

#include "opal_config.h"
#include "opal/class/opal_object.h"

Go to the source code of this file.

Data Structures

class  opal_output_stream_t
 Structure used to request the opening of a OPAL output stream. More...
 

Macros

#define OPAL_OUTPUT(a)
 Main macro for use in sending debugging output to output streams; will be "compiled out" when OPAL is configured without –enable-debug. More...
 
#define OPAL_OUTPUT_VERBOSE(a)
 Macro for use in sending debugging output to the output streams. More...
 

Typedefs

typedef struct opal_output_stream_t opal_output_stream_t
 Convenience typedef.
 

Functions

OPAL_DECLSPEC bool opal_output_init (void)
 Initializes the output stream system and opens a default "verbose" stream. More...
 
OPAL_DECLSPEC void opal_output_finalize (void)
 Shut down the output stream system. More...
 
OPAL_DECLSPEC int opal_output_open (opal_output_stream_t *lds)
 Opens an output stream. More...
 
OPAL_DECLSPEC int opal_output_reopen (int output_id, opal_output_stream_t *lds)
 Re-opens / redirects an output stream. More...
 
OPAL_DECLSPEC bool opal_output_switch (int output_id, bool enable)
 Enables and disables output streams. More...
 
OPAL_DECLSPEC void opal_output_reopen_all (void)
 
OPAL_DECLSPEC void opal_output_close (int output_id)
 Close an output stream. More...
 
OPAL_DECLSPEC void opal_output (int output_id, const char *format,...) __opal_attribute_format__(__printf__
 Main function to send output to a stream. More...
 
OPAL_DECLSPEC void
OPAL_DECLSPEC void 
opal_output_verbose (int verbose_level, int output_id, const char *format,...) __opal_attribute_format__(__printf__
 Send output to a stream only if the passed verbosity level is high enough. More...
 
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC void 
opal_output_vverbose (int verbose_level, int output_id, const char *format, va_list ap) __opal_attribute_format__(__printf__
 Same as opal_output_verbose(), but takes a va_list form of varargs.
 
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC char * 
opal_output_string (int verbose_level, int output_id, const char *format,...) __opal_attribute_format__(__printf__
 Send output to a string if the verbosity level is high enough. More...
 
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC char
OPAL_DECLSPEC char * 
opal_output_vstring (int verbose_level, int output_id, const char *format, va_list ap) __opal_attribute_format__(__printf__
 Same as opal_output_string, but accepts a va_list form of varargs.
 
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC void
OPAL_DECLSPEC char
OPAL_DECLSPEC char
OPAL_DECLSPEC void 
opal_output_set_verbosity (int output_id, int level)
 Set the verbosity level for a stream. More...
 
OPAL_DECLSPEC int opal_output_get_verbosity (int output_id)
 Get the verbosity level for a stream. More...
 
OPAL_DECLSPEC void opal_output_set_output_file_info (const char *dir, const char *prefix, char **olddir, char **oldprefix)
 Set characteristics for output files. More...
 
OPAL_DECLSPEC OBJ_CLASS_DECLARATION (opal_output_stream_t)
 Declare the class of this type. More...
 

Variables

BEGIN_C_DECLS OPAL_DECLSPEC bool opal_output_redirected_to_syslog
 
OPAL_DECLSPEC int opal_output_redirected_syslog_pri
 

Detailed Description

OPAL output stream facility.

The OPAL output stream facility is used to send output from the OPAL libraries to output devices. It is meant to fully replace all forms of printf() (and friends). Output streams are opened via the opal_output_open() function call, and then sent output via opal_output_verbose(), OPAL_OUTPUT(), and opal_output(). Streams are closed with opal_output_close().

Streams can multiplex output to several kinds of outputs (one of each):

  • the syslog (if available)
  • standard output
  • standard error
  • file

Which outputs to use are specified during opal_output_open().

WARNING: When using "file" as an output destination, be aware that the file may not exist until the session directory for the process exists. This is at least part of the way through MPI_INIT (for example). Most MCA components and internals of Open MPI won't be affected by this, but some RTE / startup aspects of Open MPI will not be able to write to a file for output. See opal_output() for details on what happens in these cases.

opal_output_open() returns an integer handle that is used in successive calls to OPAL_OUTPUT() and opal_output() to send output to the stream.

The default "verbose" stream is opened after invoking opal_output_init() (and closed after invoking opal_output_finalize()). This stream outputs to stderr only, and has a stream handle ID of 0.

It is erroneous to have one thread close a stream and have another try to write to it. Multiple threads writing to a single stream will be serialized in an unspecified order.

Macro Definition Documentation

#define OPAL_OUTPUT (   a)

Function Documentation

OPAL_DECLSPEC OBJ_CLASS_DECLARATION ( opal_output_stream_t  )

Declare the class of this type.

Note that the constructor for this class is for convenience only – it is not necessary to be invoked. If the constructor it used, it sets all values in the struct to be false / 0 (i.e., turning off all output). The intended usage is to invoke the constructor and then enable the output fields that you want.

OPAL_DECLSPEC void opal_output ( int  output_id,
const char *  format,
  ... 
)

Main function to send output to a stream.

Parameters
output_idStream id returned from opal_output_open().
formatprintf-style format string.
varargsprintf-style varargs list to fill the string specified by the format parameter.

This is the main function to send output to custom streams (note that output to the default "verbose" stream is handled through opal_output_verbose() and opal_output_error()).

It is never necessary to send a trailing "\n" in the strings to this function; some streams requires newlines, others do not – this function will append newlines as necessary.

Verbosity levels are ignored in this function.

Note that for output streams that are directed to files, the files are stored under the process' session directory. If the session directory does not exist when opal_output() is invoked, the output will be discarded! Once the session directory is created, opal_output() will automatically create the file and writing to it.

Referenced by bxor_int(), bxor_integer(), bxor_long(), max_double(), max_double_precision(), max_float(), max_real(), mca_base_param_recache_files(), mca_bml_base_btl_array_get_index(), mca_bml_base_btl_array_get_next(), mca_bml_base_btl_array_insert(), mca_btl_elan_component_init(), mca_btl_gm_component_init(), mca_btl_mx_component_init(), mca_btl_mx_component_progress(), mca_btl_mx_del_procs(), mca_btl_mx_prepare_dst(), mca_btl_mx_register(), mca_btl_mx_send(), mca_btl_sm_component_progress(), mca_btl_smcuda_component_progress(), mca_btl_tcp_component_init(), mca_mpool_grdma_finalize(), mca_mpool_rdma_finalize(), mca_mpool_rgpusm_deregister(), mca_mpool_rgpusm_finalize(), mca_mpool_rgpusm_find(), mca_mpool_rgpusm_register(), mca_oob_tcp_init(), mca_oob_tcp_msg_recv_complete(), mca_oob_tcp_msg_recv_handler(), mca_oob_tcp_msg_send_handler(), mca_oob_tcp_parse_uri(), mca_oob_tcp_peer_accept(), mca_oob_tcp_peer_close(), mca_oob_tcp_ping(), mca_oob_tcp_resolve(), mca_oob_tcp_set_socket_options(), mca_pml_bfo_error_pending_packets(), mca_pml_bfo_is_duplicate_msg(), mca_pml_bfo_recv_request_recverrnotify(), mca_pml_bfo_recv_request_rndvrestartack(), mca_pml_bfo_recv_request_rndvrestartnack(), mca_pml_bfo_repost_match_fragment(), mca_pml_bfo_send_request_rndvrestartnotify(), mca_pml_bfo_update_eager_bml_btl_recv_ctl(), mca_pml_csum_recv_frag_callback_ack(), mca_pml_csum_recv_frag_callback_fin(), mca_pml_csum_recv_frag_callback_frag(), mca_pml_csum_recv_frag_callback_match(), mca_pml_csum_recv_frag_callback_put(), mca_pml_csum_recv_frag_callback_rndv(), mca_pml_csum_recv_request_progress_rndv(), ompi_group_peer_lookup(), ompi_mpi_finalize(), ompi_mpi_init(), ompi_wait_for_debugger(), opal_cr_init(), opal_graph_print(), opal_hash_table_get_value_ptr(), opal_hash_table_get_value_uint32(), opal_hash_table_get_value_uint64(), opal_hash_table_remove_value_ptr(), opal_hash_table_remove_value_uint32(), opal_hash_table_remove_value_uint64(), opal_hash_table_set_value_ptr(), opal_hash_table_set_value_uint32(), opal_hash_table_set_value_uint64(), opal_os_dirpath_create(), opal_pointer_array_set_item(), opal_pointer_array_test_and_set_item(), orte_ess_base_orted_setup(), orte_notifier_base_open(), orte_plm_submit_launch(), orte_ras_gridengine_allocate(), orte_ras_gridengine_finalize(), orte_register_params(), orte_rmaps_base_get_target_nodes(), orte_session_dir(), orte_session_dir_cleanup(), orte_session_dir_finalize(), shmem_posix_shm_open(), sum_float(), sum_int16_t(), sum_int32_t(), and sum_int64_t().

OPAL_DECLSPEC void opal_output_close ( int  output_id)

Close an output stream.

Parameters
output_idHandle of the stream to close.

Close an output stream. No output will be sent to the stream after it is closed. Be aware that output handles tend to be re-used; it is possible that after a stream is closed, if another stream is opened, it will get the same handle value.

References OPAL_THREAD_LOCK, and OPAL_THREAD_UNLOCK.

Referenced by opal_malloc_finalize(), opal_output_finalize(), orte_ess_base_close(), and orte_finalize().

OPAL_DECLSPEC void opal_output_finalize ( void  )

Shut down the output stream system.

Shut down the output stream system, including the default verbose stream.

References opal_output_stream_t::lds_prefix, OBJ_DESTRUCT, and opal_output_close().

Referenced by opal_finalize_util().

OPAL_DECLSPEC int opal_output_get_verbosity ( int  output_id)

Get the verbosity level for a stream.

Parameters
output_idStream id returned from opal_output_open()
Returns
Verbosity of stream

Referenced by orte_ess_base_orted_setup(), and orte_rmaps_base_get_target_nodes().

OPAL_DECLSPEC bool opal_output_init ( void  )

Initializes the output stream system and opens a default "verbose" stream.

Return values
trueUpon success.
falseUpon failure.

This should be the first function invoked in the output subsystem. After this call, the default "verbose" stream is open and can be written to via calls to opal_output_verbose() and opal_output_error().

By definition, the default verbose stream has a handle ID of 0, and has a verbose level of 0.

References opal_output_stream_t::lds_prefix, opal_output_stream_t::lds_syslog_ident, opal_output_stream_t::lds_syslog_priority, opal_output_stream_t::lds_want_stderr, opal_output_stream_t::lds_want_stdout, opal_output_stream_t::lds_want_syslog, OBJ_CONSTRUCT, and opal_output_open().

Referenced by opal_init_util(), and opal_output_switch().

OPAL_DECLSPEC int opal_output_open ( opal_output_stream_t lds)

Opens an output stream.

Parameters
ldsA pointer to opal_output_stream_t describing what the characteristics of the output stream should be.

This function opens an output stream and returns an integer handle. The caller is responsible for maintaining the handle and using it in successive calls to OPAL_OUTPUT(), opal_output(), opal_output_switch(), and opal_output_close().

If lds is NULL, the default descriptions will be used, meaning that output will only be sent to stderr.

It is safe to have multiple threads invoke this function simultaneously; their execution will be serialized in an unspecified manner.

Be sure to see opal_output() for a description of what happens when open_open() / opal_output() is directed to send output to a file but the process session directory does not yet exist.

Referenced by mca_btl_base_open(), mca_coll_base_open(), mca_io_base_open(), mca_oob_base_open(), ompi_op_base_open(), ompi_osc_base_open(), opal_cr_init(), opal_malloc_init(), opal_output_init(), opal_progress_init(), orte_dt_init(), orte_errmgr_base_open(), orte_ess_base_open(), orte_grpcomm_base_open(), orte_iof_base_open(), orte_notifier_base_open(), orte_odls_base_open(), orte_plm_base_open(), orte_ras_base_open(), orte_ras_gridengine_open(), orte_register_params(), orte_rmaps_base_open(), orte_rml_base_open(), and orte_sensor_base_open().

OPAL_DECLSPEC int opal_output_reopen ( int  output_id,
opal_output_stream_t lds 
)

Re-opens / redirects an output stream.

Parameters
output_idStream handle to reopen
ldsA pointer to opal_output_stream_t describing what the characteristics of the reopened output stream should be.

This function redirects an existing stream into a new [set of] location[s], as specified by the lds parameter. If the output_id passed is invalid, this call is effectively the same as opening a new stream with a specific stream handle.

OPAL_DECLSPEC void opal_output_set_output_file_info ( const char *  dir,
const char *  prefix,
char **  olddir,
char **  oldprefix 
)

Set characteristics for output files.

Parameters
dirDirectory where output files will go
olddirIf non-NULL, the directory where output files were previously opened
prefixPrefix of files in the output directory
oldprefixIf non-NULL, the old prefix

This function controls the final filename used for all new output streams that request output files. Specifically, when opal_output_stream_t::lds_want_file is true, the output filename will be of the form $dir/$prefix$suffix.

The default value for the output directory is whatever is specified in the TMPDIR environment variable if it exists, or $HOME if it does not. The default value for the prefix is "output-pid<pid>-" (where "<pid>" is replaced by the PID of the current process).

If dir or prefix are NULL, new values are not set. The strings represented by dir and prefix are copied into internal storage; it is safe to pass string constants or free() these values after opal_output_set_output_file_info() returns.

If olddir or oldprefix are not NULL, copies of the old directory and prefix (respectively) are returned in these parameters. The caller is responsible for calling (free) on these values. This allows one to get the old values, output an output file in a specific directory and/or with a specific prefix, and then restore the old values.

Note that this function only affects the creation of new streams – streams that have already started writing to output files are not affected (i.e., their output files are not moved to the new directory). More specifically, the opal_output system only opens/creates output files lazily – so calling this function affects both new streams and any stream that was previously opened but had not yet output anything.

Referenced by orte_ess_base_orted_setup().

OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC char OPAL_DECLSPEC char OPAL_DECLSPEC void opal_output_set_verbosity ( int  output_id,
int  level 
)

Set the verbosity level for a stream.

Parameters
output_idStream id returned from opal_output_open().
levelNew verbosity level

This function sets the verbosity level on a given stream. It will be used for all future invocations of opal_output_verbose().

Referenced by mca_btl_base_open(), opal_cr_init(), and orte_dt_init().

OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC void OPAL_DECLSPEC char* opal_output_string ( int  verbose_level,
int  output_id,
const char *  format,
  ... 
)

Send output to a string if the verbosity level is high enough.

Parameters
output_idStream id returned from opal_output_open().
levelTarget verbosity level.
formatprintf-style format string.
varargsprintf-style varargs list to fill the string specified by the format parameter.

Exactly the same as opal_output_verbose(), except the output it sent to a string instead of to the stream. If the verbose level is not high enough, NULL is returned. The caller is responsible for free()'ing the returned string.

OPAL_DECLSPEC bool opal_output_switch ( int  output_id,
bool  enable 
)

Enables and disables output streams.

Parameters
output_idStream handle to switch
enableBoolean indicating whether to enable the stream output or not.
Returns
The previous enable state of the stream (true == enabled, false == disabled).

The output of a stream can be temporarily disabled by passing an enable value to false, and later resumed by passing an enable value of true. This does not close the stream – it simply tells the opal_output subsystem to intercept and discard any output sent to the stream via OPAL_OUTPUT() or opal_output() until the output is re-enabled.

References opal_output_init().

OPAL_DECLSPEC void OPAL_DECLSPEC void opal_output_verbose ( int  verbose_level,
int  output_id,
const char *  format,
  ... 
)

Send output to a stream only if the passed verbosity level is high enough.

Parameters
output_idStream id returned from opal_output_open().
levelTarget verbosity level.
formatprintf-style format string.
varargsprintf-style varargs list to fill the string specified by the format parameter.

Output is only sent to the stream if the current verbosity level is greater than or equal to the level parameter. This mechanism can be used to send "information" kinds of output to user applications, but only when the user has asked for a high enough verbosity level.

It is never necessary to send a trailing "\n" in the strings to this function; some streams requires newlines, others do not – this function will append newlines as necessary.

This function is really a convenience wrapper around checking the current verbosity level set on the stream, and if the passed level is less than or equal to the stream's verbosity level, this function will effectively invoke opal_output to send the output to the stream.

See also
opal_output_set_verbosity()

Referenced by btl_openib_handle_failover_control_messages(), error_out_all_pending_frags(), mca_btl_base_select(), mca_btl_openib_endpoint_notify(), mca_btl_openib_handle_endpoint_error(), mca_coll_base_comm_select(), mca_coll_base_find_available(), mca_io_base_delete(), mca_io_base_file_select(), mca_mpool_rgpusm_register(), mca_oob_base_init(), mca_pml_bfo_check_recv_ctl_completion_status(), mca_pml_bfo_completion_sendreq_has_error(), mca_pml_bfo_error_pending_packets(), mca_pml_bfo_get_request(), mca_pml_bfo_is_duplicate_fin(), mca_pml_bfo_is_duplicate_msg(), mca_pml_bfo_recv_frag_callback_recverrnotify(), mca_pml_bfo_recv_frag_callback_rndvrestartack(), mca_pml_bfo_recv_frag_callback_rndvrestartnack(), mca_pml_bfo_recv_frag_callback_rndvrestartnotify(), mca_pml_bfo_recv_request_recverrnotify(), mca_pml_bfo_recv_request_rndvrestartack(), mca_pml_bfo_recv_request_rndvrestartnack(), mca_pml_bfo_repost_fin(), mca_pml_bfo_repost_match_fragment(), mca_pml_bfo_rndvrestartnotify_completion(), mca_pml_bfo_send_request_restart(), mca_pml_bfo_send_request_rndvrestartnotify(), mca_pml_bfo_update_rndv_fields(), ompi_op_base_op_select(), opal_cr_init(), orte_ess_base_close(), orte_notifier_base_select(), orte_rml_base_select(), orte_sensor_base_select(), and shmem_posix_shm_open().