Changeset 6076 in vbox for trunk/include

Timestamp:

Dec 14, 2007 7:23:03 PM (17 years ago)

Author:

vboxsync

Message:

Merged dmik/s2 branch (r25959:26751) to the trunk.

Location:

trunk/include

Files:

• VBox/com/Guid.h (modified) (8 diffs)
• VBox/com/assert.h (modified) (3 diffs)
• VBox/com/defs.h (modified) (4 diffs)
• VBox/com/string.h (modified) (5 diffs)
• VBox/settings.h (added)
• iprt/assert.h (modified) (18 diffs)
• iprt/cdefs.h (modified) (1 diff)
• iprt/cpputils.h (modified) (2 diffs)

trunk/include/VBox/com/Guid.h

@@ +1 @@
+/* $Id$ */
+
 /** @file
  * MS COM / XPCOM Abstraction Layer:
@@ -34 +36 @@
 #include "VBox/com/string.h"
 
+#include <iprt/cpputils.h>
 #include <iprt/uuid.h>
 
@@ -51 +54 @@
     Guid (const RTUUID &that) { uuid = that; }
     Guid (const GUID &that) { ::memcpy (&uuid, &that, sizeof (GUID)); }
-    Guid (const char *that) {
+    Guid (const char *that)
+    {
         ::RTUuidClear (&uuid);
         ::RTUuidFromStr (&uuid, that);
     }
 
-    Guid &operator= (const Guid &that) {
+    Guid &operator= (const Guid &that)
+    {
         ::memcpy (&uuid, &that.uuid, sizeof (RTUUID));
         return *this;
     }
-    Guid &operator= (const GUID &guid) {
+    Guid &operator= (const GUID &guid)
+    {
         ::memcpy (&uuid, &guid, sizeof (GUID));
         return *this;
     }
-    Guid &operator= (const RTUUID &guid) {
+    Guid &operator= (const RTUUID &guid)
+    {
         ::memcpy (&uuid, &guid, sizeof (RTUUID));
         return *this;
     }
-    Guid &operator= (const char *str) {
+    Guid &operator= (const char *str)
+    {
         ::RTUuidFromStr (&uuid, str);
         return *this;
@@ -76 +84 @@
     void clear() { ::RTUuidClear (&uuid); }
 
-    Utf8Str toString () const {
+    Utf8Str toString () const
+    {
         char buf [RTUUID_STR_LENGTH];
         ::RTUuidToStr (&uuid, buf, RTUUID_STR_LENGTH);
@@ -92 +101 @@
     bool operator< (const GUID &guid) const { return ::RTUuidCompare (&uuid, (PRTUUID) &guid) < 0; }
 
-    // to pass instances as GUIDPARAM parameters to interface methods
+    /* to pass instances as GUIDPARAM parameters to interface methods */
     operator const GUID &() const { return *(GUID *) &uuid; }
 
-    // to directly pass instances to CFGLDRQueryUUID()
+    /* to directly pass instances to CFGLDRQueryUUID() */
     PRTUUID ptr() { return &uuid; }
 
-    // to pass instances to printf-like functions
+    /* to pass instances to printf-like functions */
     PCRTUUID raw() const { return &uuid; }
 
-    // to pass instances to RTUuid*() as a constant argument
+    /* to pass instances to RTUuid*() as a constant argument */
     operator const RTUUID * () const { return &uuid; }
 
 #if defined(RT_OS_WINDOWS)
 
-    // to assign instances to GUIDPARAMOUT parameters from within the interface method
-    const Guid &cloneTo (GUID *pguid) const {
+    /* to assign instances to GUIDPARAMOUT parameters from within the
+     *  interface method */
+    const Guid &cloneTo (GUID *pguid) const
+    {
         if (pguid) { ::memcpy (pguid, &uuid, sizeof (GUID)); }
         return *this;
     }
 
-    // to pass instances as GUIDPARAMOUT parameters to interface methods
+    /* to pass instances as GUIDPARAMOUT parameters to interface methods */
     GUID *asOutParam() { return (GUID *) &uuid; }
 
 #else
 
-    // to assign instances to GUIDPARAMOUT parameters from within the interface method
-    const Guid &cloneTo (nsID **ppguid) const {
+    /* to assign instances to GUIDPARAMOUT parameters from within the
+     * interface method */
+    const Guid &cloneTo (nsID **ppguid) const
+    {
         if (ppguid) { *ppguid = (nsID *) nsMemory::Clone (&uuid, sizeof (nsID)); }
         return *this;
     }
 
-    // internal helper class for asOutParam()
-    class GuidOutParam {
+    /* internal helper class for asOutParam() */
+    class GuidOutParam
+    {
         GuidOutParam (Guid &guid) : ptr (0), outer (guid) { outer.clear(); }
         nsID *ptr;
@@ -132 +146 @@
     public:
         operator nsID **() { return &ptr; }
-        ~GuidOutParam() {
+        ~GuidOutParam()
+        {
             if (ptr && outer.isEmpty()) { outer = *ptr; nsMemory::Free (ptr); }
         }
@@ -138 +153 @@
     };
 
-    // to pass instances as GUIDPARAMOUT parameters to interface methods
+    /* to pass instances as GUIDPARAMOUT parameters to interface methods */
     GuidOutParam asOutParam() { return GuidOutParam (*this); }
 
 #endif
 
-    // to directly test GUIDPARAM interface method's parameters
-    static BOOL isEmpty (const GUID &guid) { return ::RTUuidIsNull ((PRTUUID) &guid); }
+    /* to directly test GUIDPARAM interface method's parameters */
+    static bool isEmpty (const GUID &guid)
+    {
+        return ::RTUuidIsNull ((PRTUUID) &guid) != 0;
+    }
+
+    /** 
+     *  Static immutable empty object. May be used for comparison purposes.
+     */
+    static const Guid Empty;
 
 private:
@@ -151 +174 @@
 };
 
-#if defined (_MSC_VER)
-
-// work around error C2593 of the stupid MSVC 7.x ambiguity resolver
-inline bool operator! (const Guid& guid) { return !bool (guid); }
-inline bool operator&& (const Guid& guid, bool b) { return bool (guid) && b; }
-inline bool operator|| (const Guid& guid, bool b) { return bool (guid) || b; }
-inline bool operator&& (bool b, const Guid& guid) { return b && bool (guid); }
-inline bool operator|| (bool b, const Guid& guid) { return b || bool (guid); }
-
-#endif
+/* work around error C2593 of the stupid MSVC 7.x ambiguity resolver */
+WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP (Guid);
 
 } /* namespace com */
 
-#endif
+#endif /* ___VBox_com_Guid_h */
 

trunk/include/VBox/com/assert.h

@@ -79 +79 @@
 
 /**
+ *  A special version of AssertComRC that evaluates the given expression and
+ *  throws it if the result code is failed.
+ *
+ *  @param rc   COM result code
+ *  @param eval the expression to evaluate
+ */
+#define AssertComRCThrow(rc, eval)      \
+    if (1) { AssertComRC (rc); if (!SUCCEEDED (rc)) { throw (eval); } } else do {} while (0)
+
+/**
  *  A special version of AssertComRC that just breaks if the result code is
  *  failed.
@@ -88 +98 @@
 
 /**
+ *  A special version of AssertComRC that just throws @a rc if the result code is
+ *  failed.
+ *
+ *  @param rc   COM result code
+ */
+#define AssertComRCThrowRC(rc)          \
+    if (1) { AssertComRC (rc); if (!SUCCEEDED (rc)) { throw rc; } } else do {} while (0)
+
+/**
  *  Checks whether the given COM result code is successful.
  *  If not, executes the return statement with this result code.
@@ -104 +123 @@
 #define CheckComRCBreakRC(rc)      \
     if (1) { if (!SUCCEEDED (rc)) { break; } } else do {} while (0)
+
+/**
+ *  Checks whether the given COM result code is successful.
+ *  If not, throws the given COM result.
+ *
+ *  @param rc   COM result code
+ */
+#define CheckComRCThrowRC(rc)      \
+    if (1) { if (!SUCCEEDED (rc)) { throw rc; } } else do {} while (0)
 
 /*

trunk/include/VBox/com/defs.h

@@ -77 +77 @@
 #define COM_IIDOF(I) _ATL_IIDOF (I)
 
-#else // defined (RT_OS_WINDOWS)
+#else /* defined (RT_OS_WINDOWS) */
 
 #error "VBOX_WITH_XPCOM is not defined!"
 
-#endif // defined (RT_OS_WINDOWS)
-
-#else // !defined (VBOX_WITH_XPCOM)
+#endif /* defined (RT_OS_WINDOWS) */
+
+#else /* !defined (VBOX_WITH_XPCOM) */
 
 // XPCOM
@@ -101 +101 @@
 #undef TRUE
 
-#endif // defined (RT_OS_OS2)
+#endif /* defined (RT_OS_OS2) */
 
 #if defined (RT_OS_DARWIN)
@@ -289 +289 @@
 }
 
-#endif // !defined (RT_OS_WINDOWS)
+#endif /* !defined (RT_OS_WINDOWS) */
 
 /**
@@ -304 +304 @@
 #endif
 
-#endif
-
+#endif /* ___VBox_com_defs_h */
+

trunk/include/VBox/com/string.h

@@ +1 @@
+/* $Id$ */
+
 /** @file
  * MS COM / XPCOM Abstraction Layer:
@@ -36 +38 @@
 
 #include <iprt/string.h>
+#include <iprt/cpputils.h>
 #include <iprt/alloc.h>
 
@@ -208 +211 @@
     BSTR *asOutParam() { setNull(); return &bstr; }
 
+    /** 
+     *  Static immutable null object. May be used for comparison purposes.
+     */
+    static const Bstr Null;
+
 private:
 
@@ -417 +425 @@
     char **asOutParam() { setNull(); return &str; }
 
+    /** 
+     *  Static immutable null object. May be used for comparison purposes.
+     */
+    static const Utf8Str Null;
+
 private:
 
@@ -568 +581 @@
 } /* namespace com */
 
-#endif
+#endif /* ___VBox_com_string_h */

trunk/include/iprt/assert.h

@@ -235 +235 @@
 #endif
 
+/** @def AssertBreakVoid
+ * Assert that an expression is true and breaks if it isn't.
+ * In RT_STRICT mode it will hit a breakpoint before returning.
+ *
+ * @param   expr    Expression which should be true.
+ */
+#ifdef RT_STRICT
+# define AssertBreakVoid(expr) \
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+        { \
+            AssertMsg1(#expr, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+            AssertBreakpoint(); \
+            break; \
+        } \
+    } while (0)
+#else
+# define AssertBreakVoid(expr) \
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+            break; \
+    } while (0)
+#endif
+
 
 /** @def AssertMsg
@@ -334 +358 @@
 #endif
 
+/** @def AssertMsgBreakVoid
+ * Assert that an expression is true and breaks if it isn't.
+ * In RT_STRICT mode it will hit a breakpoint before returning.
+ *
+ * @param   expr    Expression which should be true.
+ * @param   a       printf argument list (in parenthesis).
+ */
+#ifdef RT_STRICT
+# define AssertMsgBreakVoid(expr, a)  \
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+        { \
+            AssertMsg1(#expr, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+            AssertMsg2 a; \
+            AssertBreakpoint(); \
+            break; \
+        } \
+    } while (0)
+#else
+# define AssertMsgBreakVoid(expr, a) \
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+            break; \
+    } while (0)
+#endif
+
 
 /** @def AssertFailed
@@ -407 +457 @@
 #endif
 
+/** @def AssertFailedBreakVoid
+ * An assertion failed, hit breakpoint (RT_STRICT mode only) and break.
+ */
+#ifdef RT_STRICT
+# define AssertFailedBreakVoid()  \
+    do { \
+        AssertMsg1((const char *)0, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+        AssertBreakpoint(); \
+        break; \
+    } while (0)
+#else
+# define AssertFailedBreakVoid()  \
+    do { \
+        break; \
+    } while (0)
+#endif
+
 
 /** @def AssertMsgFailed
@@ -488 +555 @@
         break; \
     } else do {} while (0)
+#endif
+
+/** @def AssertMsgFailedBreakVoid
+ * An assertion failed, hit breakpoint with message (RT_STRICT mode only) and break.
+ *
+ * @param   a       printf argument list (in parenthesis).
+ */
+#ifdef RT_STRICT
+# define AssertMsgFailedBreakVoid(a)  \
+    do { \
+        AssertMsg1((const char *)0, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+        AssertMsg2 a; \
+        AssertBreakpoint(); \
+        break; \
+    } while (0)
+#else
+# define AssertMsgFailedBreakVoid(a)  \
+    do { \
+        break; \
+    } while (0)
 #endif
 
@@ -564 +651 @@
  */
 #define AssertReleaseBreak(expr, stmt)  \
-    if (RT_UNLIKELY(!(expr))) { \
-        AssertMsg1(#expr, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
-        AssertReleaseBreakpoint(); \
-        stmt; \
-        break; \
-    } else do {} while (0)
-
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+        { \
+            AssertMsg1(#expr, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+            AssertReleaseBreakpoint(); \
+            stmt; \
+            break; \
+        } \
+    } while (0)
+
+/** @def AssertReleaseBreakVoid
+ * Assert that an expression is true, hit a breakpoing and break if it isn't.
+ *
+ * @param   expr    Expression which should be true.
+ */
+#define AssertReleaseBreakVoid(expr)  \
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+        { \
+            AssertMsg1(#expr, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+            AssertReleaseBreakpoint(); \
+            break; \
+        } \
+    } while (0)
 
 
@@ -607 +711 @@
     } while (0)
 
-/** @def AssertReleaseMsgReturn
+/** @def AssertReleaseMsgReturnVoid
  * Assert that an expression is true, print the message and hit a breakpoint and return if it isn't.
  *
@@ -641 +745 @@
     } else do {} while (0)
 
+/** @def AssertReleaseMsgBreakVoid
+ * Assert that an expression is true, print the message and hit a breakpoint and break if it isn't.
+ *
+ * @param   expr    Expression which should be true.
+ * @param   a       printf argument list (in parenthesis).
+ */
+#define AssertReleaseMsgBreakVoid(expr, a)  \
+    do { \
+        if (RT_UNLIKELY(!(expr))) \
+        { \
+            AssertMsg1(#expr, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+            AssertMsg2 a; \
+            AssertReleaseBreakpoint(); \
+            break; \
+        } \
+    } while (0)
+
 
 /** @def AssertReleaseFailed
@@ -663 +784 @@
     } while (0)
 
-/** @def AssertReleaseFailedReturn
+/** @def AssertReleaseFailedReturnVoid
  * An assertion failed, hit a breakpoint and return.
  */
@@ -686 +807 @@
         break; \
     } else do {} while (0)
+
+/** @def AssertReleaseFailedBreakVoid
+ * An assertion failed, hit a breakpoint and break.
+ */
+#define AssertReleaseFailedBreakVoid()  \
+    do { \
+        AssertMsg1((const char *)0, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+        AssertReleaseBreakpoint(); \
+        break; \
+    } while (0)
 
 
@@ -743 +874 @@
     } else do {} while (0)
 
+/** @def AssertReleaseMsgFailedBreakVoid
+ * An assertion failed, print a message, hit a breakpoint and break.
+ *
+ * @param   a   printf argument list (in parenthesis).
+ */
+#define AssertReleaseMsgFailedBreakVoid(a) \
+    do { \
+        AssertMsg1((const char *)0, __LINE__, __FILE__, __PRETTY_FUNCTION__); \
+        AssertMsg2 a; \
+        AssertReleaseBreakpoint(); \
+        break; \
+    } while (0)
 
 
@@ -841 +984 @@
 #define AssertRCBreak(rc, stmt)   AssertMsgRCBreak(rc, ("%Vra\n", (rc)), stmt)
 
+/** @def AssertRCBreakVoid
+ * Asserts a iprt status code successful, bitch (RT_STRICT mode only) and break if it isn't.
+ *
+ * @param   rc      iprt status code.
+ * @remark  rc is references multiple times. In release mode is NOREF()'ed.
+ */
+#define AssertRCBreakVoid(rc)   AssertMsgRCBreakVoid(rc, ("%Vra\n", (rc)))
+
 /** @def AssertMsgRC
  * Asserts a iprt status code successful.
@@ -891 +1042 @@
     do { AssertMsgBreak(RT_SUCCESS_NP(rc), msg, stmt); NOREF(rc); } while (0)
 
+/** @def AssertMsgRCBreakVoid
+ * Asserts a iprt status code successful and if it's not break.
+ *
+ * If RT_STRICT is defined the message will be printed and a breakpoint hit before it breaks
+ *
+ * @param   rc      iprt status code.
+ * @param   msg     printf argument list (in parenthesis).
+ * @remark  rc is references multiple times. In release mode is NOREF()'ed.
+ */
+#define AssertMsgRCBreakVoid(rc, msg) \
+    do { AssertMsgBreakVoid(RT_SUCCESS(rc), msg); NOREF(rc); } while (0)
+
 /** @def AssertRCSuccess
  * Asserts an iprt status code equals VINF_SUCCESS.
@@ -927 +1090 @@
 #define AssertRCSuccessBreak(rc, stmt)    AssertMsgBreak((rc) == VINF_SUCCESS, ("%Vra\n", (rc)), stmt)
 
+/** @def AssertRCSuccessBreakVoid
+ * Asserts that an iprt status code equals VINF_SUCCESS, bitch (RT_STRICT mode only) and break if it isn't.
+ *
+ * @param   rc      iprt status code.
+ * @remark  rc is references multiple times. In release mode is NOREF()'ed.
+ */
+#define AssertRCSuccessBreakVoid(rc)    AssertMsgBreakVoid((rc) == VINF_SUCCESS, ("%Vra\n", (rc)))
+
 
 /** @def AssertReleaseRC
@@ -973 +1144 @@
 #define AssertReleaseRCBreak(rc, stmt) AssertReleaseMsgRCBreak(rc, ("%Vra\n", (rc)), stmt)
 
+/** @def AssertReleaseRCBreakVoid
+ * Asserts a iprt status code successful, breaking if it isn't.
+ *
+ * On failure information about the error will be printed, a breakpoint hit
+ * and finally breaking the current statement if the breakpoint is somehow ignored.
+ *
+ * @param   rc      iprt status code.
+ * @remark  rc is references multiple times.
+ */
+#define AssertReleaseRCBreakVoid(rc) AssertReleaseMsgRCBreakVoid(rc, ("%Vra\n", (rc)))
+
 /** @def AssertReleaseMsgRC
  * Asserts a iprt status code successful.
@@ -1022 +1204 @@
 #define AssertReleaseMsgRCBreak(rc, msg, stmt)    AssertReleaseMsgBreak(RT_SUCCESS_NP(rc), msg, stmt)
 
+/** @def AssertReleaseMsgRCBreakVoid
+ * Asserts a iprt status code successful.
+ *
+ * On failure a custom message is printed, a breakpoint is hit, and finally
+ * breaking the current status if the breakpoint is showhow ignored.
+ *
+ * @param   rc      iprt status code.
+ * @param   msg     printf argument list (in parenthesis).
+ * @remark  rc is references multiple times.
+ */
+#define AssertReleaseMsgRCBreakVoid(rc, msg)    AssertReleaseMsgBreakVoid(RT_SUCCESS(rc), msg)
+
 /** @def AssertReleaseRCSuccess
  * Asserts that an iprt status code equals VINF_SUCCESS.
@@ -1067 +1261 @@
 #define AssertReleaseRCSuccessBreak(rc, stmt)     AssertReleaseMsgBreak((rc) == VINF_SUCCESS, ("%Vra\n", (rc)), stmt)
 
+/** @def AssertReleaseRCSuccessBreakVoid
+ * Asserts that an iprt status code equals VINF_SUCCESS.
+ *
+ * On failure information about the error will be printed, a breakpoint hit
+ * and finally breaking the current statement if the breakpoint is somehow ignored.
+ *
+ * @param   rc      iprt status code.
+ * @remark  rc is references multiple times.
+ */
+#define AssertReleaseRCSuccessBreakVoid(rc)     AssertReleaseMsgBreakVoid((rc) == VINF_SUCCESS, ("%Vra\n", (rc)))
+
 
 /** @def AssertFatalRC
@@ -1130 +1335 @@
 #define AssertPtrBreak(pv, stmt)  AssertMsgBreak(VALID_PTR(pv), ("%p\n", (pv)), stmt)
 
+/** @def AssertPtrBreakVoid
+ * Asserts that a pointer is valid.
+ *
+ * @param   pv      The pointer.
+ */
+#define AssertPtrBreakVoid(pv)  AssertMsgBreakVoid(VALID_PTR(pv), ("%p\n", (pv)))
+
 /** @def AssertPtrNull
  * Asserts that a pointer is valid or NULL.
@@ -1159 +1371 @@
  */
 #define AssertPtrNullBreak(pv, stmt)  AssertMsgBreak(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)), stmt)
+
+/** @def AssertPtrNullBreakVoid
+ * Asserts that a pointer is valid or NULL.
+ *
+ * @param   pv      The pointer.
+ */
+#define AssertPtrNullBreakVoid(pv)  AssertMsgBreakVoid(VALID_PTR(pv) || (pv) == NULL, ("%p\n", (pv)))
 
 

trunk/include/iprt/cdefs.h

@@ -1248 +1248 @@
 #ifdef __cplusplus
 
+/** @def DECLEXPORT_CLASS
+ * How to declare an exported class. Place this macro after the 'class'
+ * keyword in the declaration of every class you want to export.
+ *
+ * @note It is necessary to use this macro even for inner classes declared
+ * inside the already exported classes. This is a GCC specific requirement,
+ * but it seems not to harm other compilers.
+ */
+#if defined(_MSC_VER) || defined(RT_OS_OS2)
+# define DECLEXPORT_CLASS       __declspec(dllexport)
+#else
+# ifdef VBOX_HAVE_VISIBILITY_HIDDEN
+#  define DECLEXPORT_CLASS      __attribute__((visibility("default")))
+# else
+#  define DECLEXPORT_CLASS
+# endif
+#endif
+
+/** @def DECLIMPORT_CLASS
+ * How to declare an imported class Place this macro after the 'class'
+ * keyword in the declaration of every class you want to export.
+ *
+ * @note It is necessary to use this macro even for inner classes declared
+ * inside the already exported classes. This is a GCC specific requirement,
+ * but it seems not to harm other compilers.
+ */
+#if defined(_MSC_VER) || (defined(RT_OS_OS2) && !defined(__IBMC__) && !defined(__IBMCPP__))
+# define DECLIMPORT_CLASS       __declspec(dllimport)
+#else
+# ifdef VBOX_HAVE_VISIBILITY_HIDDEN
+#  define DECLIMPORT_CLASS      __attribute__((visibility("default")))
+# else
+#  define DECLIMPORT_CLASS
+# endif
+#endif
+
 /** @def WORKAROUND_MSVC7_ERROR_C2593_FOR_BOOL_OP
  * Macro to work around error C2593 of the not-so-smart MSVC 7.x ambiguity

trunk/include/iprt/cpputils.h

@@ -26 +26 @@
 #ifndef ___iprt_cpputils_h
 #define ___iprt_cpputils_h
+
+#include <iprt/assert.h>
+
+#include <memory>
 
 /** @defgroup grp_rt_cpputils   C++ Utilities
@@ -61 +65 @@
 inline C *unconst (const C *that) { return const_cast <C *> (that); }
 
+
+/** 
+ * Extensions to the std namespace.
+ */
+namespace stdx
+{
+
+/* forward */
+template <class> class auto_ref_ptr;
+
+/** 
+ * Base class for objects willing to support smart reference counting using
+ * the auto_ref_ptr template.
+ *
+ * When a class that wants to be used with the auto_ref_ptr template it simply
+ * declares the auto_ref class among its public base classes -- there is no
+ * need to implement any additional methods.
+ */
+class auto_ref
+{
+protected:
+
+    auto_ref() : mRefs (0) {}
+
+    /** Increases the reference counter and returns it */
+    size_t ref() { return ++ mRefs; }
+
+    /** Decreases the reference counter and returns it */
+    size_t unref() { Assert (mRefs > 0); return -- mRefs; }
+
+private:
+
+    size_t mRefs;
+
+    template <class> friend class auto_ref_ptr;
+};
+
+/**
+ * The auto_ref_ptr template manages pointers to objects that support
+ * reference counting by implementing auto_ref or a similar interface.
+ *
+ * Pointer management includes the following key points:
+ *
+ *   1) Automatic increment of the reference counter when a pointer to the
+ *      object of the managed class or another auto_ptr_instance of the same
+ *      type is assigned to the given auto_ref_ptr instance.
+ *   2) Automatic decrement of the reference counter when the given
+ *      auto_ref_ptr instance is destroyed (for example, as a result of
+ *      leaving the scope) or berfore it is assigned a new object pointer.
+ *   3) Automatic deletion of the managed object pointer whenever its
+ *      reference counter reaches zero after a decrement.
+ *   4) Providing the dereference operator that gives direct access to the
+ *      managed pointer.
+ *
+ * The object class to manage must provide ref() and unref() methods that have
+ * the same syntax and symantics as defined in the auto_ref class.
+ *
+ * @param C     Class to manage.
+ */
+template <class C>
+class auto_ref_ptr
+{
+public:
+
+    /** 
+     * Creates a null instance that does not manage anything.
+     */
+    auto_ref_ptr() : m (NULL) {}
+
+    /** 
+     * Creates an instance that starts managing the given pointer.
+     *
+     * @param a Pointer to manage.
+     */
+    auto_ref_ptr (C* a) : m (a) { if (m) m->ref(); }
+
+    /** 
+     * Creates an instance that starts managing the pointer managed
+     * by the given object.
+     *
+     * @param that Object to manage.
+     */
+    auto_ref_ptr (const auto_ref_ptr &that) : m (that.m) { if (m) m->ref(); }
+
+    ~auto_ref_ptr() { do_unref(); }
+    
+    /** 
+     * Assigns the given pointer to this instance and starts managing it.
+     *
+     * @param a Pointer to assign.
+     */
+    auto_ref_ptr &operator= (C *a) { do_reref (a); return *this; }
+
+    /** 
+     * Assigns the given pointer to this instance and starts managing it.
+     *
+     * @param a Pointer to assign.
+     */
+    auto_ref_ptr &operator= (const auto_ref_ptr &that) { do_reref (that.m); return *this; }
+
+    /** 
+     * Returns @c true if this instance is null and false otherwise.
+     */
+    bool is_null() const { return m == NULL; }
+
+    /** 
+     * Dereferences the instance by returning the managed pointer.
+     * Asserts that the managed pointer is not NULL.
+     */
+    C *operator-> () const { AssertMsg (m, ("Managed pointer is NULL!\n")); return m; }
+
+    /** 
+     * Returns the managed pointer or NULL if this instance is null.
+     */
+    C *raw() const { return m; }
+
+    /** 
+     * Compares this auto_ref_ptr instance another instance and returns @c
+     * true if both instances manage the same or @c NULL pointer.
+     *
+     * Note that this method doesn't try to compare objects managed pointers
+     * point to because that would a) break the common 'pointer to something'
+     * semantics auto_ref_ptr tries to follow and b) require to define the
+     * comparison operator in the managed class which is not always possible.
+     * You may analyze pointed objects yourself if you need more precise
+     * comparison.
+     * 
+     * @param that Object to compare this object with.
+     */
+    bool operator== (const auto_ref_ptr &that) const
+    {
+        return m == that.m;
+    }
+
+protected:
+
+    void do_reref (C *a)
+    {
+        /* be aware of self assignment */
+        if (a)
+            a->ref();
+        if (m)
+        {
+            size_t refs = m->unref();
+            if (refs == 0)
+            {
+                refs = 1; /* stabilize */
+                delete m;
+            }
+        }
+        m = a;
+    }
+
+    void do_unref() { do_reref (NULL); }
+
+    C *m;
+};
+
+/** 
+ * The exception_trap_base class is an abstract base class for all
+ * exception_trap template instantiations.
+ *
+ * Pointer variables of this class are used to store a pointer any object of
+ * any class instantiated from the exception_trap template, or in other words
+ * to store a full copy of any exception wrapped into the exception_trap instance
+ * allocated on the heap.
+ *
+ * See the exception_trap template for more info.
+ */
+class exception_trap_base
+{
+public:
+
+    virtual void rethrow() = 0;
+};
+
+/** 
+ * The exception_trap template acts like a wrapper for the given exception
+ * class that stores a full copy of the exception and therefore allows to
+ * rethrow it preserving the actual type information about the exception
+ * class.
+ *
+ * This functionality is useful in situations where it is necessary to catch a
+ * (known) number of exception classes and pass the caught exception instance
+ * to an upper level using a regular variable (rather than the exception
+ * unwinding mechanism itself) *and* preserve all information about the type
+ * (class) of the caight exception so that it may be rethrown on the upper
+ * level unchanged.
+ *
+ * Usage pattern:
+ * @code
+    using namespace std;
+    using namespace stdx;
+
+    auto_ptr <exception_trap_base> trapped;
+
+    int callback();
+
+    int safe_callback()
+    {   
+      try
+      {
+        // callback may throw a set of exceptions but we don't want it to start
+        // unwinding the stack right now
+
+        return callback();
+      }
+      catch (const MyException &err) { trapped = new_exception_trap (err); }
+      catch (const MyException2 &err) { trapped = new_exception_trap (err); }
+      catch (...) { trapped = new_exception_trap (logic_error()); }
+
+      return -1;
+    }
+
+    void bar()
+    {
+      // call a funciton from some C library that supports callbacks but knows
+      // nothing about exceptions so throwing one from a callback will leave
+      // the library in an undetermined state
+
+      do_something_with_callback (safe_callback());
+
+      // check if we have got an exeption from callback() and rethrow it now
+      // when we are not in the C library any more
+      if (trapped.get() != NULL)
+        trapped->rethrow();
+    }
+ * @endcode
+ * 
+ * @param T Exception class to wrap.
+ */
+template <typename T>
+class exception_trap : public exception_trap_base
+{
+public:
+
+    exception_trap (const T &aTrapped) : trapped (aTrapped) {}
+    void rethrow() { throw trapped; }
+
+    T trapped;
+};
+
+/** 
+ * Convenience function that allocates a new exception_trap instance on the
+ * heap by automatically deducing the exception_trap template argument from
+ * the type of the exception passed in @a aTrapped.
+ *
+ * The following two lines of code inside the catch block are equivalent:
+ *
+ * @code
+    using namespace std;
+    using namespace stdx;
+    catch (const MyException &err)
+    {
+      auto_ptr <exception_trap_base> t1 = new exception_trap <MyException> (err);
+      auto_ptr <exception_trap_base> t2 = new_exception_trap (err);
+    }
+ * @endcode
+ * 
+ * @param aTrapped Exception to put to the allocated trap.
+ * 
+ * @return Allocated exception_trap object.
+ */
+template <typename T>
+static exception_trap <T> *
+new_exception_trap (const T &aTrapped)
+{
+    return new exception_trap <T> (aTrapped);
+}
+
+/**
+ * Enhancement of std::auto_ptr <char> intended to take pointers to char
+ * buffers allocated using new[].
+ *
+ * This differs from std::auto_ptr <char> so that it overloads some methods to
+ * uses delete[] instead of delete to delete the owned data in order to
+ * conform to the C++ standard (and avoid valgrind complaints).
+ *
+ * Note that you should not use instances of this class where pointers or
+ * references to objects of std::auto_ptr <char> are expeced. Despite the fact
+ * the classes are related, the base is not polymorphic (in particular,
+ * neither the destructor nor the reset() method are virtual). It means that when
+ * acessing instances of this class through the base pointer, overloaded
+ * methods won't be called.
+ */
+class char_auto_ptr : public std::auto_ptr <char>
+{
+public:
+
+    explicit char_auto_ptr (char *a = 0) throw()
+        : std::auto_ptr <char> (a) {}
+
+    /* Note: we use unconst brute force below because the non-const version
+     * of the copy constructor won't accept temporary const objects
+     * (e.g. function return values) in GCC. std::auto_ptr has the same
+     * "problem" but it seems overcome it using #pragma GCC system_header
+     * which doesn't work here. */
+    char_auto_ptr (const char_auto_ptr &that) throw()
+        : std::auto_ptr <char> (unconst (that).release()) {}
+
+    ~char_auto_ptr() { delete[] (release()); }
+
+    char_auto_ptr &operator= (char_auto_ptr &that) throw()
+    {
+        std::auto_ptr <char>::operator= (that);
+        return *this;
+    }
+
+    void reset (char *a) throw()
+    {
+        if (a != get())
+        {
+            delete[] (release());
+            std::auto_ptr <char>::reset (a);
+        }
+    }
+};
+
+} /* namespace stdx */
+
 /** @} */