rayelliott
/
barrier
mirror of https://github.com/debauchee/barrier.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

added doxygen comments for all relevant headers in base.

This commit is contained in:
crs 2002-07-26 18:28:18 +00:00
parent 879cf26f8d
commit 7a461855eb
10 changed files with 380 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
base/CFunctionJob.h
View File

@ -3,8 +3,13 @@
#include "IJob.h" #include "IJob.h"
//! Use a function as a job
/*!
A job class that invokes a function.
*/
class CFunctionJob : public IJob { class CFunctionJob : public IJob {
public: public:
//! run() invokes \c func(arg)
CFunctionJob(void (*func)(void*), void* arg = NULL); CFunctionJob(void (*func)(void*), void* arg = NULL);
virtual ~CFunctionJob(); virtual ~CFunctionJob();

163
base/CLog.h
View File

@ -4,54 +4,114 @@
#include "common.h" #include "common.h"
#include <stdarg.h> #include <stdarg.h>
//! Logging facility
/*!
The logging class; all console output should go through this class.
It supports multithread safe operation, several message priority levels,
filtering by priority, and output redirection. The macros log() and
clog() provide convenient access.
*/
class CLog { class CLog {
public: public:
enum { //! Log levels
kFATAL, /*!
kERROR, The logging priority levels in order of highest to lowest priority.
kWARNING, */
kNOTE, enum ELevel {
kINFO, kFATAL, //!< For fatal errors
kDEBUG, kERROR, //!< For serious errors
kDEBUG1, kWARNING, //!< For minor errors and warnings
kDEBUG2 kNOTE, //!< For messages about notable events
kINFO, //!< For informational messages
kDEBUG, //!< For important debugging messages
kDEBUG1, //!< For more detailed debugging messages
kDEBUG2 //!< For even more detailed debugging messages
}; };
// type of outputter function. return false if CLog should use //! Outputter function.
// the default outputter, true otherwise. /*!
typedef bool (*Outputter)(int priority, const char*); Type of outputter function. The outputter should write \c message,
which has the given \c priority, to a log and return true. Or it can
return false to let CLog use the default outputter.
*/
typedef bool (*Outputter)(int priority, const char* message);
// type of lock/unlock function //! Locking function
/*!
Type of lock/unlock function. If \c lock is true then block other
threads that try to lock until this thread unlocks. If \c lock is
false then unlock and allow another (waiting) thread to lock.
*/
typedef void (*Lock)(bool lock); typedef void (*Lock)(bool lock);
// print a log message //! @name manipulators
static void print(const char*, ...); //@{
static void printt(const char* file, int line, const char*, ...);
// get/set the function used to write the log. a NULL outputter //! Set the function used to write the log
// means to use the default which is fprintf(stderr, ...). note /*!
// that the outputter should not call CLog methods but, if it Sets the function used to write to the log. The outputter function
// does, the current lock function must permit recursive locks. is called with the formatted string to write and the priority level.
CLog will have already filtered messages below the current filter
priority. A NULL outputter means to use the default which is to print
to stderr. Note that the outputter should not call CLog methods but,
if it does, the current lock function must permit recursive locks.
*/
static void setOutputter(Outputter); static void setOutputter(Outputter);
static Outputter getOutputter();
// get/set the lock/unlock function. use setLock(NULL) to remove //! Set the lock/unlock function
// the locking function. note that the lock function is used when /*!
// retrieving the lock function. there is no default lock function. Set the lock/unlock function. Use setLock(NULL) to remove the
locking function. There is no default lock function; do not call
CLog from multiple threads unless a working lock function has been
installed.
*/
static void setLock(Lock); static void setLock(Lock);
static Lock getLock();
// get/set the minimum priority filter. any message below this //! Set the minimum priority filter.
// priority is discarded. the default priority is 4 (INFO) /*!
// (unless built without NDEBUG in which case it's 5 (DEBUG)). Set the filter. Messages below this priority are discarded.
// the default can be overridden by setting the SYN_LOG_PRI env The default priority is 4 (INFO) (unless built without NDEBUG
// var to "FATAL", "ERROR", etc. setFilter(const char*) returns in which case it's 5 (DEBUG)). The default can be overridden
// true if the priority name was recognized; if name == NULL by setting the SYN_LOG_PRI env var to "FATAL", "ERROR", etc.
// then it simply returns true. setFilter(const char*) returns true if the priority \c name was
recognized; if \c name is NULL then it simply returns true.
*/
static bool setFilter(const char* name); static bool setFilter(const char* name);
static void setFilter(int); static void setFilter(int);
//@}
//! @name accessors
//@{
//! Print a log message
/*!
Print a log message using the printf-like \c format and arguments.
*/
static void print(const char* format, ...);
//! Print a log message
/*!
Print a log message using the printf-like \c format and arguments
preceded by the filename and line number.
*/
static void printt(const char* file, int line,
const char* format, ...);
//! Get the function used to write the log
static Outputter getOutputter();
//! Get the lock/unlock function
/*!
Get the lock/unlock function. Note that the lock function is
used when retrieving the lock function.
*/
static Lock getLock();
//! Get the minimum priority level.
static int getFilter(); static int getFilter();
//@}
private: private:
class CHoldLock { class CHoldLock {
public: public:
@ -75,6 +135,45 @@ private:
static int s_maxPriority; static int s_maxPriority;
}; };
/*!
\def log(arg)
Write to the log. Because macros cannot accept variable arguments, this
should be invoked like so:
\code
log((CLOG_XXX "%d and %d are %s", x, y, x == y ? "equal" : "not equal"));
\endcode
In particular, notice the double open and close parentheses. Also note
that there is no comma after the \c CLOG_XXX. The \c XXX should be
replaced by one of enumerants in \c CLog::ELevel without the leading
\c k. For example, \c CLOG_INFO. The special \c CLOG_PRINT level will
not be filtered and is never prefixed by the filename and line number.
If \c NOLOGGING is defined during the build then this macro expands to
nothing. If \c NDEBUG is defined during the build then it expands to a
call to CLog::print. Otherwise it expands to a call to CLog::printt,
which includes the filename and line number.
*/
/*!
\def logc(expr, arg)
Write to the log if and only if expr is true. Because macros cannot accept
variable arguments, this should be invoked like so:
\code
clog(x == y, (CLOG_XXX "%d and %d are equal", x, y));
\endcode
In particular, notice the parentheses around everything after the boolean
expression. Also note that there is no comma after the \c CLOG_XXX.
The \c XXX should be replaced by one of enumerants in \c CLog::ELevel
without the leading \c k. For example, \c CLOG_INFO. The special
\c CLOG_PRINT level will not be filtered and is never prefixed by the
filename and line number.
If \c NOLOGGING is defined during the build then this macro expands to
nothing. If \c NDEBUG is defined during the build then it expands to a
call to CLog::print. Otherwise it expands to a call to CLog::printt,
which includes the filename and line number.
*/
#if defined(NOLOGGING) #if defined(NOLOGGING)
#define log(_a1) #define log(_a1)
#define logc(_a1, _a2) #define logc(_a1, _a2)

79
base/CStopwatch.h
View File

@ -3,47 +3,84 @@
#include "common.h" #include "common.h"
//! A timer class
/*!
This class measures time intervals. All time interval measurement
should use this class.
*/
class CStopwatch { class CStopwatch {
public: public:
// the default constructor does an implicit reset() or setTrigger(). /*!
// if triggered == false then the clock starts ticking. The default constructor does an implicit reset() or setTrigger().
If triggered == false then the clock starts ticking.
*/
CStopwatch(bool triggered = false); CStopwatch(bool triggered = false);
~CStopwatch(); ~CStopwatch();
// manipulators //! @name manipulators
//@{
// set the start time to the current time, returning the time since //! Reset the timer to zero
// the last reset. this does not remove the trigger if it's set nor /*!
// does it start a stopped clock. if the clock is stopped then Set the start time to the current time, returning the time since
// subsequent reset()'s will return 0. the last reset. This does not remove the trigger if it's set nor
does it start a stopped clock. If the clock is stopped then
subsequent reset()'s will return 0.
*/
double reset(); double reset();
// stop and start the stopwatch. while stopped, no time elapses. //! Stop the timer
// stop() does not remove the trigger but start() does, even if /*!
// the clock was already started. Stop the stopwatch. The time interval while stopped is not
counted by the stopwatch. stop() does not remove the trigger.
Has no effect if already stopped.
*/
void stop(); void stop();
//! Start the timer
/*!
Start the stopwatch. start() removes the trigger, even if the
stopwatch was already started.
*/
void start(); void start();
// setTrigger() stops the clock like stop() except there's an //! Stop the timer and set the trigger
// implicit start() the next time (non-const) getTime() is called. /*!
// this is useful when you want the clock to start the first time setTrigger() stops the clock like stop() except there's an
// you check it. implicit start() the next time (non-const) getTime() is called.
This is useful when you want the clock to start the first time
you check it.
*/
void setTrigger(); void setTrigger();
// return the time since the last reset() (or call reset() and //! Get elapsed time
// return zero if the trigger is set). /*!
Returns the time since the last reset() (or calls reset() and
returns zero if the trigger is set).
*/
double getTime(); double getTime();
//! Same as getTime()
operator double(); operator double();
//@}
//! @name accessors
//@{
// accessors //! Check if timer is stopped
/*!
// returns true if the watch is stopped Returns true if the stopwatch is stopped.
*/
bool isStopped() const; bool isStopped() const;
// return the time since the last reset(). these cannot trigger // return the time since the last reset().
// the clock to start so if the trigger is set it's as if it wasn't. //! Get elapsed time
/*!
Returns the time since the last reset(). This cannot trigger the
stopwatch to start and will not clear the trigger.
*/
double getTime() const; double getTime() const;
//! Same as getTime() const
operator double() const; operator double() const;
//@}
private: private:
double getClock() const; double getClock() const;

86
base/CString.h
View File

@ -6,45 +6,83 @@
#include <string> #include <string>
#include "stdpost.h" #include "stdpost.h"
// use standard C++ string class for our string class
typedef std::string CString; typedef std::string CString;
//! String utilities
/*!
This class provides various functions for string manipulation.
*/
class CStringUtil { class CStringUtil {
public: public:
// format a string using positional arguments. fmt has literal //! Format positional arguments
// characters and conversion specifications introduced by `%': /*!
// %% literal `%' Format a string using positional arguments. fmt has literal
// %{n} positional element n, n a positive integer, {} are literal characters and conversion specifications introduced by `\%':
// all arguments in the variable list are const char*. positional - \c\%\% -- literal `\%'
// elements are indexed from 1. - \c\%{n} -- positional element n, n a positive integer, {} are literal
All arguments in the variable list are const char*. Positional
elements are indexed from 1.
*/
static CString format(const char* fmt, ...); static CString format(const char* fmt, ...);
//! Format positional arguments
/*!
Same as format() except takes va_list.
*/
static CString vformat(const char* fmt, va_list); static CString vformat(const char* fmt, va_list);
// print a string using printf-style formatting //! Print a string using printf-style formatting
/*!
Equivalent to printf() except the result is returned as a CString.
*/
static CString print(const char* fmt, ...); static CString print(const char* fmt, ...);
//! Print a string using printf-style formatting
/*!
Same as print() except takes va_list.
*/
static CString vprint(const char* fmt, va_list); static CString vprint(const char* fmt, va_list);
// like print but print into a given buffer. if the resulting string //! Print a string using printf-style formatting into a buffer
// will not fit into the buffer then a new buffer is allocated and /*!
// returned, otherwise the input buffer is returned. the caller must This is like print but print into a given buffer. If the resulting
// delete[] the returned buffer if is not the passed-in buffer. string will not fit into \c buffer then a new buffer is allocated and
// returned, otherwise \c buffer is returned. the caller must delete[]
// prefix and suffix must be >= 0. exactly prefix characters and the returned memory if is not \c buffer.
// at least suffix characters are available in the buffer before
// and after the printed string, respectively. bufferLength is the \c prefix and \c suffix must be >= 0. Exactly \c prefix characters and
// length of buffer and should not be adjusted by the caller to at least \c suffix characters are available in the buffer before
// account for prefix or suffix. and after the printed string, respectively. \c bufferLength is the
length of buffer and should not be adjusted by the caller to
account for \c prefix or \c suffix.
*/
static char* vsprint(char* buffer, int bufferLength, static char* vsprint(char* buffer, int bufferLength,
int prefix, int suffix, const char* fmt, va_list); int prefix, int suffix, const char* fmt, va_list);
//! Case-insensitive comparisons
/*!
This class provides case-insensitve comparison functions.
*/
class CaselessCmp { class CaselessCmp {
public: public:
bool operator()(const CString&, const CString&) const; //! Same as less()
static bool less(const CString&, const CString&); bool operator()(const CString& a, const CString& b) const;
static bool equal(const CString&, const CString&);
static bool cmpLess(const CString::value_type&, //! Returns true iff \c a is lexicographically less than \c b
const CString::value_type&); static bool less(const CString& a, const CString& b);
static bool cmpEqual(const CString::value_type&,
const CString::value_type&); //! Returns true iff \c a is lexicographically equal to \c b
static bool equal(const CString& a, const CString& b);
//! Returns true iff \c a is lexicographically less than \c b
static bool cmpLess(const CString::value_type& a,
const CString::value_type& b);
//! Returns true iff \c a is lexicographically equal to \c b
static bool cmpEqual(const CString::value_type& a,
const CString::value_type& b);
}; };
}; };

89
base/CUnicode.h
View File

@ -5,33 +5,100 @@
#include "BasicTypes.h" #include "BasicTypes.h"
#include <wchar.h> #include <wchar.h>
//! Unicode utility functions
/*!
This class provides functions for converting between various Unicode
encodings and the current locale encoding.
*/
class CUnicode { class CUnicode {
public: public:
// returns true iff the string contains a valid sequence of UTF-8 //! @name accessors
// encoded characters. //@{
//! Test UTF-8 string for validity
/*!
Returns true iff the string contains a valid sequence of UTF-8
encoded characters.
*/
static bool isUTF8(const CString&); static bool isUTF8(const CString&);
// convert from UTF-8 encoding to other encodings. if errors is //! Convert from UTF-8 to UCS-2 encoding
// not NULL then it gets true if any characters could not be /*!
// encoded in the target encoding and false otherwise. note Convert from UTF-8 to UCS-2. If errors is not NULL then *errors
// that decoding errors do not set errors to error. UTF8ToText() is set to true iff any character could not be encoded in UCS-2.
// converts to the current locale's (multibyte) encoding. Decoding errors do not set *errors.
*/
static CString UTF8ToUCS2(const CString&, bool* errors = NULL); static CString UTF8ToUCS2(const CString&, bool* errors = NULL);
//! Convert from UTF-8 to UCS-4 encoding
/*!
Convert from UTF-8 to UCS-4. If errors is not NULL then *errors
is set to true iff any character could not be encoded in UCS-4.
Decoding errors do not set *errors.
*/
static CString UTF8ToUCS4(const CString&, bool* errors = NULL); static CString UTF8ToUCS4(const CString&, bool* errors = NULL);
//! Convert from UTF-8 to UTF-16 encoding
/*!
Convert from UTF-8 to UTF-16. If errors is not NULL then *errors
is set to true iff any character could not be encoded in UTF-16.
Decoding errors do not set *errors.
*/
static CString UTF8ToUTF16(const CString&, bool* errors = NULL); static CString UTF8ToUTF16(const CString&, bool* errors = NULL);
//! Convert from UTF-8 to UTF-32 encoding
/*!
Convert from UTF-8 to UTF-32. If errors is not NULL then *errors
is set to true iff any character could not be encoded in UTF-32.
Decoding errors do not set *errors.
*/
static CString UTF8ToUTF32(const CString&, bool* errors = NULL); static CString UTF8ToUTF32(const CString&, bool* errors = NULL);
//! Convert from UTF-8 to the current locale encoding
/*!
Convert from UTF-8 to the current locale encoding. If errors is not
NULL then *errors is set to true iff any character could not be encoded.
Decoding errors do not set *errors.
*/
static CString UTF8ToText(const CString&, bool* errors = NULL); static CString UTF8ToText(const CString&, bool* errors = NULL);
// convert from some encoding to UTF-8. if errors is not NULL //! Convert from UCS-2 to UTF-8
// then it gets true if any characters could not be decoded and /*!
// false otherwise. textToUTF8() converts from the current Convert from UCS-2 to UTF-8. If errors is not NULL then *errors is
// locale's (multibyte) encoding. set to true iff any character could not be decoded.
*/
static CString UCS2ToUTF8(const CString&, bool* errors = NULL); static CString UCS2ToUTF8(const CString&, bool* errors = NULL);
//! Convert from UCS-4 to UTF-8
/*!
Convert from UCS-4 to UTF-8. If errors is not NULL then *errors is
set to true iff any character could not be decoded.
*/
static CString UCS4ToUTF8(const CString&, bool* errors = NULL); static CString UCS4ToUTF8(const CString&, bool* errors = NULL);
//! Convert from UTF-16 to UTF-8
/*!
Convert from UTF-16 to UTF-8. If errors is not NULL then *errors is
set to true iff any character could not be decoded.
*/
static CString UTF16ToUTF8(const CString&, bool* errors = NULL); static CString UTF16ToUTF8(const CString&, bool* errors = NULL);
//! Convert from UTF-32 to UTF-8
/*!
Convert from UTF-32 to UTF-8. If errors is not NULL then *errors is
set to true iff any character could not be decoded.
*/
static CString UTF32ToUTF8(const CString&, bool* errors = NULL); static CString UTF32ToUTF8(const CString&, bool* errors = NULL);
//! Convert from the current locale encoding to UTF-8
/*!
Convert from the current locale encoding to UTF-8. If errors is not
NULL then *errors is set to true iff any character could not be decoded.
*/
static CString textToUTF8(const CString&, bool* errors = NULL); static CString textToUTF8(const CString&, bool* errors = NULL);
//@}
private: private:
// convert UTF8 to wchar_t string (using whatever encoding is native // convert UTF8 to wchar_t string (using whatever encoding is native
// to the platform). caller must delete[] the returned string. the // to the platform). caller must delete[] the returned string. the

6
base/IInterface.h
View File

@ -3,8 +3,14 @@
#include "common.h" #include "common.h"
//! Base class of interfaces
/*!
This is the base class of all interface classes. An interface class has
only pure virtual methods.
*/
class IInterface { class IInterface {
public: public:
//! Interface destructor does nothing
virtual ~IInterface() { } virtual ~IInterface() { }
}; };

5
base/IJob.h
View File

@ -3,8 +3,13 @@
#include "IInterface.h" #include "IInterface.h"
//! Job interface
/*!
A job is an interface for executing some function.
*/
class IJob : public IInterface { class IJob : public IInterface {
public: public:
//! Run the job
virtual void run() = 0; virtual void run() = 0;
}; };

5
base/TMethodJob.h
View File

@ -3,9 +3,14 @@
#include "IJob.h" #include "IJob.h"
//! Use a function as a job
/*!
A job class that invokes a member function.
*/
template <class T> template <class T>
class TMethodJob : public IJob { class TMethodJob : public IJob {
public: public:
//! run() invokes \c object->method(arg)
TMethodJob(T* object, void (T::*method)(void*), void* arg = NULL); TMethodJob(T* object, void (T::*method)(void*), void* arg = NULL);
virtual ~TMethodJob(); virtual ~TMethodJob();

34
base/XBase.h
View File

@ -6,9 +6,15 @@
#include <exception> #include <exception>
#include "stdpost.h" #include "stdpost.h"
//! Exception base class
/*!
This is the base class of most exception types.
*/
class XBase : public std::exception { class XBase : public std::exception {
public: public:
//! Use getWhat() as the result of what()
XBase(); XBase();
//! Use \c msg as the result of what()
XBase(const CString& msg); XBase(const CString& msg);
virtual ~XBase(); virtual ~XBase();
@ -16,10 +22,15 @@ public:
virtual const char* what() const; virtual const char* what() const;
protected: protected:
// returns a human readable string describing the exception //! Get a human readable string describing the exception
virtual CString getWhat() const throw() = 0; virtual CString getWhat() const throw() = 0;
// look up a message and format it //! Format a string
/*!
Looks up a message format using \c id, using \c defaultFormat if
no format can be found, then replaces positional parameters in
the format string and returns the result.
*/
virtual CString format(const char* id, virtual CString format(const char* id,
const char* defaultFormat, ...) const throw(); const char* defaultFormat, ...) const throw();
@ -27,18 +38,29 @@ private:
mutable CString m_what; mutable CString m_what;
}; };
//! Mix-in for handling \c errno
/*!
This mix-in class for exception classes provides storage and query of
\c errno.
*/
class MXErrno { class MXErrno {
public: public:
//! Save \c errno as the error code
MXErrno(); MXErrno();
MXErrno(int); //! Save \c err as the error code
MXErrno(int err);
// manipulators //! @name accessors
//@{
// accessors
//! Get the error code
int getErrno() const; int getErrno() const;
//! Get the human readable string for the error code
const char* getErrstr() const; const char* getErrstr() const;
//@}
private: private:
int m_errno; int m_errno;
}; };

2
base/common.h
View File

@ -1,6 +1,8 @@
#ifndef COMMON_H #ifndef COMMON_H
#define COMMON_H #define COMMON_H
// this file should be included, directly or indirectly by every other.
#if HAVE_CONFIG_H #if HAVE_CONFIG_H
# include "config.h" # include "config.h"
#endif #endif