w_stat.h

/*<std-header orig-src='shore' incl-file-exclusion='W_STAT_H'>

 $Id: w_stat.h,v 1.1 2010/05/26 01:20:26 nhall Exp $

SHORE -- Scalable Heterogeneous Object REpository

Copyright (c) 1994-99 Computer Sciences Department, University of
                      Wisconsin -- Madison
All Rights Reserved.

Permission to use, copy, modify and distribute this software and its
documentation is hereby granted, provided that both the copyright
notice and this permission notice appear in all copies of the
software, derivative works or modified versions, and any portions
thereof, and that both notices appear in supporting documentation.

THE AUTHORS AND THE COMPUTER SCIENCES DEPARTMENT OF THE UNIVERSITY
OF WISCONSIN - MADISON ALLOW FREE USE OF THIS SOFTWARE IN ITS
"AS IS" CONDITION, AND THEY DISCLAIM ANY LIABILITY OF ANY KIND
FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.

This software was developed with support by the Advanced Research
Project Agency, ARPA order number 018 (formerly 8230), monitored by
the U.S. Army Research Laboratory under contract DAAB07-91-C-Q518.
Further funding for this work was provided by DARPA through
Rome Research Laboratory Contract No. F30602-97-2-0247.

*/

#ifndef W_STAT_H
#define W_STAT_H

#include "w_defines.h"

/*  -- do not edit anything above this line --   </std-header>*/

#ifdef __GNUG__
#pragma interface
#endif

#ifndef W_BASE_H
#include <w_base.h>
#endif
#ifndef W_RC_H
#include <w_rc.h>
#endif

class w_statistics_t; // forward
class w_stat_module_t; // forward

/**\page STATS Sets of Statistics
 * Each library (and the client, if you so choose) may have
 * its own collection of statistics. To enable rapid addition and
 * modifying of the counters kept, a Perl script takes a brief
 * description of the statistics and genenerates a series of files
 * for including in your source code.
 *
 * \section STATSOUT Output
 * The Perl script stats.pl in tools/ takes a file  (usually
 * named something like xxx_stats.dat) of the form:
 * \code
 * name1 name2 = mask class {
 *    type STATNAME    Descriptive string
 *    type STATNAME    Descriptive string
 *     ...
 *    type STATNAME    Descriptive string
 *    }
 * \endcode
 *
 * - "name1" and "name2" are no longer used by the
 *         storage manager, but must be present.
 *
 * - "mask" can be in octal (0777777), hex (0xabcdeff) or decimal 
 *         notation. It should be unique among statistics modules.
 *         It is no longer used by the storage manager but must be present.
 *
 * - "class" is required. Output file names contain the class name as a prefix.
 *
 * - "type" must be a one-word type:
 *        - base_stat, unsigned int, unsigned long, unsigned,
 *          u_int, u_long, int, long, ulong are synonyms for base_stat_t 
 *        - float, base_float, and double are synonyms for base_float_t
 *
 * - STATNAME is the attribute name of the counter in the C++ class.
 *        These attribute names are generated in the output for inclusion
 *        in code that declares the class.
 *
 * - "Descriptive string" will be quoted by the translator.  Don't
 *        put it in quotes in the .dat file.
 *
 * \section STATSOUT Output
 *  for each class  this script creates:
 
 *  - <class>_dec_gen.cpp : definition of 
 *         <class>& operator -= (<class> &, const <class> &);
 *  - <class>_inc_gen.cpp : definition of 
 *         <class>& operator += (<class> &, const <class> &);
 *  - <class>_out_gen.cpp : definition of 
 *         <class>& operator << (ostream &, const <class> &);
 *  - <class>_collect_gen.cpp : contains code used by virtual table
 *                    code. Not for general use.
 *  - <class>_struct_gen.h : contains list of attribute members for the class:w
 *  - <class>_collect_enum_gen.h :  Enumeration values used by virtual
 *                    table code. Not for general use.
 *  - <class>_msg_gen.h : the descriptive strings. 
 *
 *  Use as follows:
 *  \code
 *  class <class> {
 *  public:
 *  #include "<class>_struct_gen.h"
 *      <class>() { ... }
 *      ~<class>() { ... }
 *      void clear() {
 *          memset((void *)this, '\0', sizeof(*this));
 *      }
 *  };
 *
 *  #include "<class>_inc_gen.cpp"
 *  #include "<class>_dec_gen.cpp"
 *  #include "<class>_out_gen.cpp"
 *
 *  const char *<class>::stat_names[] = {
 *  #include "<class>_msg_gen.h"
 *  }
 *
 *  \endcode
 */

/**\brief A single statistic punning structure. 
 *
 * This structure holds a single generic statistic, be it an integer or
 * a floating-point number.  These are the statistics that are described
 * in inputs to a Perl script, and whose handling-code is generated by that script.
 * See \ref STATS.
 *
 * This struct doesn't do much; it's a union of the two numeric types
 * w_base_t::base_stat_t and w_base_t::base_float_t.
 * With this class you output the contents to an output stream,  and
 * compare two stats (equal, not-equal).
 */
class w_stat_t 
{
    friend class w_statistics_t;
    friend class w_stat_module_t;
    /* grot */
    friend ostream    & operator<<(ostream &out, const w_statistics_t &s);

protected:
    union {
        w_base_t::base_stat_t   i;
        w_base_t::base_float_t  f;
    }_u;

public:
    /// Initialize to zero.
    w_stat_t() { _u.i=0; }

    /// Initialize to integer i.
    w_stat_t(int  i) { _u.i=i; }
    operator int() const { return _u.i; }

    /// Initialize to floating point i.
    w_stat_t(w_base_t::base_float_t i) { _u.f=i; }

    /// Interpret as a floating point.
    operator w_base_t::base_float_t() const { return _u.f; }

    friend bool    operator==(const w_stat_t &, const w_stat_t &);
    friend bool    operator!=(const w_stat_t &, const w_stat_t &);

};

/*<std-footer incl-file-exclusion='W_STAT_H'>  -- do not edit anything below this line -- */

#endif          /*</std-footer>*/

---