ball_transmission.h

Go to the documentation of this file.

/// @file ball_transmission.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// ball_transmission.h                                                -*-C++-*-
#ifndef INCLUDED_BALL_TRANSMISSION
#define INCLUDED_BALL_TRANSMISSION
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup ball_transmission ball_transmission
/// @brief  Enumerate the set of states for log record transmission.
/// @addtogroup bal
/// @{
/// @addtogroup ball
/// @{
/// @addtogroup ball_transmission
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#ball_transmission-purpose"> Purpose</a>
/// * <a href="#ball_transmission-classes"> Classes </a>
/// * <a href="#ball_transmission-description"> Description </a>
///   * <a href="#ball_transmission-usage"> Usage </a>
///     * <a href="#ball_transmission-example-1-syntax"> Example 1: Syntax </a>
///     * <a href="#ball_transmission-example-2-logging"> Example 2: Logging </a>
///
/// # Purpose {#ball_transmission-purpose}
/// Enumerate the set of states for log record transmission.
///
/// # Classes {#ball_transmission-classes}
///
/// -  ball::Transmission: namespace for log record transmission states
///
/// @see  ball_context, ball_observer
///
/// # Description {#ball_transmission-description}
/// This component provides a namespace, `ball::Transmission`, for
/// the `enum` type `ball::Transmission::Cause`.  `Cause` enumerates the list of
/// conditions (or states) that can cause a log record to be transmitted.  In
/// addition, this component supports functions that convert the `Cause`
/// enumerators to a well-defined ASCII representation.
///
/// ## Usage {#ball_transmission-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Syntax {#ball_transmission-example-1-syntax}
///
///
/// The following snippets of code provide a simple illustration of
/// `ball::Transmission` usage.
///
/// First create a variable `cause` of type `ball::Transmission::Cause` and
/// initialize it to the value `ball::Transmission::e_TRIGGER_ALL`:
/// @code
/// ball::Transmission::Cause cause = ball::Transmission::e_TRIGGER_ALL;
/// @endcode
/// Next, store a pointer to its ASCII representation in a variable `asciiCause`
/// of type `const char *`:
/// @code
/// const char *asciiCause = ball::Transmission::toAscii(cause);
/// assert(0 == strcmp(asciiCause, "TRIGGER_ALL"));
/// @endcode
/// Finally, print the value of `cause` to `bsl::cout`.
/// @code
/// bsl::cout << cause << bsl::endl;
/// @endcode
/// This statement produces the following output on `stdout`:
/// @code
/// TRIGGER_ALL
/// @endcode
///
/// ### Example 2: Logging {#ball_transmission-example-2-logging}
///
///
/// The `Cause` enumeration defined in this component allows a logging system
/// to describe the condition causing the publication of a log message.  One
/// possible interpretation of three of these conditions is as follows:
///
///  `e_PASSTHROUGH`:
///    indicate that a message is being output as a stand-alone message.
/// 
///  `e_TRIGGER`:
///    indicate that a message is being output as part of a dump of all
///    messages archived for the current thread.
/// 
///  `e_TRIGGER_ALL`:
///     indicate that a message is being output as part of a dump of all
///     messages archived for *all* threads.
///
/// This example illustrates the use of `ball::Transmission::Cause` by a
/// hypothetical logging system.
///
/// We define a simple logger class named `my_Logger`.  Assume that `my_Logger`
/// accepts messages from clients (e.g., the threads in a multi-threaded
/// application) and archives them in-core.  Further assume that the message
/// archive is bounded in size in which case `my_Logger` removes older messages
/// to make room for newer ones as the need arises.  When a thread encounters
/// an unusual, unexpected, or undesirable condition that it wishes to bring to
/// the attention of an operator (say, sitting at a console terminal), it
/// "publishes" the message.  That is the role of the `publish` method in the
/// interface of `my_Logger`:
/// @code
/// // my_logger.h
///
/// class my_Logger {
///   // ...
///   public:
///     my_Logger();
///     ~my_Logger();
///     void publish(const char *message, ball::Transmission::Cause cause);
///     // ...
/// };
/// @endcode
/// The `publish` method, defined in the following, shows the different actions
/// that are taken for the three distinct causes of log message publication:
/// @code
/// // my_logger.cpp
///
/// my_Logger::my_Logger() { }
///
/// my_Logger::~my_Logger() { }
///
/// void my_Logger::publish(const char                *message,
///                         ball::Transmission::Cause  cause)
/// {
///     using namespace std;
///     switch (cause) {
///       case ball::Transmission::e_PASSTHROUGH: {
///         cout << ball::Transmission::toAscii(cause) << ":\t" << message
///              << endl;
///       } break;
///       case ball::Transmission::e_TRIGGER: {
///         cout << ball::Transmission::toAscii(cause) << ":\t" << message
///              << endl;
///         cout << "\t[ dump all messages archived for current thread ]"
///              << endl;
///       } break;
///       case ball::Transmission::e_TRIGGER_ALL: {
///         cout << ball::Transmission::toAscii(cause) << ":\t" << message
///              << endl;
///         cout << "\t[ dump all messages archived for *all* threads ]"
///              << endl;
///       } break;
///       default: {
///         cout << "***ERROR*** Unsupported Message Cause: "  << message
///              << endl;
///         return;
///       } break;
///     }
/// }
///
/// // ...
/// @endcode
/// Finally, we create a `my_Logger` object and `publish` three (simplistic)
/// messages, each with a different cause:
/// @code
/// my_Logger logger;
///
/// const char *MSG_PASSTHROUGH = "report relatively minor problem";
/// const char *MSG_TRIGGER     = "report serious thread-specific problem";
/// const char *MSG_TRIGGER_ALL = "report process-impacting problem";
///
/// logger.publish(MSG_PASSTHROUGH, ball::Transmission::e_PASSTHROUGH);
/// logger.publish(MSG_TRIGGER,     ball::Transmission::e_TRIGGER);
/// logger.publish(MSG_TRIGGER_ALL, ball::Transmission::e_TRIGGER_ALL);
/// @endcode
/// The following output is produced on `stdout`:
/// @code
/// PASSTHROUGH:    report relatively minor problem
/// TRIGGER:        report serious thread-specific problem
///                 [ dump all messages archived for current thread ]
/// TRIGGER_ALL:    report process-impacting problem
///                 [ dump all messages archived for *all* threads ]
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup ball
 * @{
 */
/** @addtogroup ball_transmission
 * @{
 */
 
#include <balscm_version.h>
 
#include <bsl_iosfwd.h>
 
 
namespace ball {
 
                        // ===================
                        // struct Transmission
                        // ===================
 
/// This struct provides a namespace for enumerating the causes of the
/// transmission of a log record.
///
/// See @ref ball_transmission 
struct Transmission {
 
  public:
    // TYPES
 
    enum Cause {
        e_PASSTHROUGH        = 0,  // single record emitted; caused locally
        e_TRIGGER            = 1,  // all records emitted; caused locally
        e_TRIGGER_ALL        = 2,  // all records emitted; caused remotely
        e_MANUAL_PUBLISH     = 3,  // manually publish a single record
        e_MANUAL_PUBLISH_ALL = 4,  // manually publish all records
        e_END                = 5   // not supported, do not use
    };
 
    /// Define `LENGTH` to be the number of consecutively-valued enumerators
    /// in the range `[ e_PASSTHROUGH .. e_MANUAL_PUBLISH_ALL ]`.
    enum {
        e_LENGTH = e_MANUAL_PUBLISH_ALL + 1
    };
 
  private:
    // PRIVATE CLASS METHODS
 
    /// Write to the specified `stream` the string representation of the
    /// specified enumeration `value`.
    static void print(bsl::ostream& stream, Transmission::Cause value);
 
  public:
    // CLASS METHODS
 
    /// Format the specified `value` to the specified output `stream` and
    /// return a reference to the modifiable `stream`.
    static bsl::ostream& streamOut(bsl::ostream&       stream,
                                   Transmission::Cause value);
 
    /// Return the string representation exactly matching the enumerator
    /// name corresponding to the specified enumeration `value`.
    static const char *toAscii(Transmission::Cause value);
};
 
// FREE OPERATORS
 
/// Format the specified `rhs` to the specified output `stream` and return a
/// reference to the modifiable `stream`.
bsl::ostream& operator<<(bsl::ostream& stream, Transmission::Cause rhs);
 
// ============================================================================
//                              INLINE DEFINITIONS
// ============================================================================
 
                        // -------------------
                        // struct Transmission
                        // -------------------
 
// CLASS METHODS
inline
bsl::ostream& Transmission::streamOut(bsl::ostream&       stream,
                                      Transmission::Cause value)
{
    print(stream, value);
    return stream;
}
 
}  // close package namespace
 
// FREE OPERATORS
inline
bsl::ostream& ball::operator<<(bsl::ostream& stream, Transmission::Cause rhs)
{
    return Transmission::streamOut(stream, rhs);
}
 
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */