From d71771d6b020db2ace30c7e62be97de1aa047ba4 Mon Sep 17 00:00:00 2001 From: Stephan Bergmann Date: Mon, 29 Oct 2001 11:42:54 +0000 Subject: #88337# Minor documentation improvements. --- salhelper/inc/salhelper/simplereferenceobject.hxx | 82 +++++++++++++++-------- 1 file changed, 53 insertions(+), 29 deletions(-) (limited to 'salhelper/inc') diff --git a/salhelper/inc/salhelper/simplereferenceobject.hxx b/salhelper/inc/salhelper/simplereferenceobject.hxx index 0cbb303b8736..a40b0cc63cbb 100755 --- a/salhelper/inc/salhelper/simplereferenceobject.hxx +++ b/salhelper/inc/salhelper/simplereferenceobject.hxx @@ -2,9 +2,9 @@ * * $RCSfile: simplereferenceobject.hxx,v $ * - * $Revision: 1.1 $ + * $Revision: 1.2 $ * - * last change: $Author: sb $ $Date: 2001-06-05 15:20:37 $ + * last change: $Author: sb $ $Date: 2001-10-29 12:42:54 $ * * The Contents of this file are made available subject to the terms of * either of the following licenses @@ -80,6 +80,32 @@ namespace salhelper { +/** A simple base implementation for reference-counted objects. + + Classes that want to implement a reference-counting mechanism based on the + acquire()/release() interface should derive from this class. + + The reason to have class local operators new and delete here is technical. + Imagine a class D derived from SimpleReferenceObject, but implemented in + another shared library that happens to use different global operators new + and delete from those used in this shared library (which, sadly, seems to + be possible with shared libraries). Now, without the class local + operators new and delete here, a code sequence like "new D" would use the + global operator new as found in the other shared library, while the code + sequence "delete this" in release() would use the global operator delete + as found in this shared library---and these two operators would not be + guaranteed to match. + + There are no overloaded operators new and delete for placement new here, + because it is felt that the concept of placement new does not work well + with the concept of reference-counted objects; so it seems best to simply + leave those operators out. + + The same problem as with operators new and delete would also be there with + operators new[] and delete[]. But since arrays of reference-counted + objects are of no use, anyway, it seems best to simply declare and not + define (private) operators new[] and delete[]. + */ class SimpleReferenceObject { public: @@ -97,38 +123,22 @@ public: inline void release() SAL_THROW(()) { if (osl_decrementInterlockedCount(&m_nCount) == 0) delete this; } - /** @descr - The reason to have class local operators new and delete here is - technical. Imagine a class D derived from SimpleReferenceObject, but - implemented in another shared library that happens to use different - global operators new and delete from those used in this shared library - (which, sadly, seems to be possible with shared libraries...). Now, - without the class local operators new and delete here, a code sequence - like "new D" would use the global operator new as found in the other - shared library, while the code sequence "delete this" in release() - would use the global operator delete as found in this shared library - ---and these two operators would not be guaranteed to match. - - @descr - There are no overloaded operators new and delete for placement new - here, because it is felt that the concept of placement new does not - work well with the concept of a reference counted object; so it seems - best to simply leave those operators out. - - @descr - The same problem as with operators new and delete would also be there - with operators new[] and delete[]. But since arrays of reference - counted objects are of no use, anyway, it seems best to simply declare - and not define (private) operators new[] and delete[]. + /** see general class documentation */ static void * operator new(std::size_t nSize) SAL_THROW((std::bad_alloc)); + /** see general class documentation + */ static void * operator new(std::size_t nSize, std::nothrow_t const & rNothrow) SAL_THROW(()); + /** see general class documentation + */ static void operator delete(void * pPtr) SAL_THROW(()); + /** see general class documentation + */ static void operator delete(void * pPtr, std::nothrow_t const & rNothrow) SAL_THROW(()); @@ -138,11 +148,25 @@ protected: private: oslInterlockedCount m_nCount; - SimpleReferenceObject(SimpleReferenceObject &); // not implemented - void operator =(SimpleReferenceObject); // not implemented + /** not implemented + @internal + */ + SimpleReferenceObject(SimpleReferenceObject &); - static void * operator new[](std::size_t); // not implemented - static void operator delete[](void * pPtr); // not implemented + /** not implemented + @internal + */ + void operator =(SimpleReferenceObject); + + /** not implemented (see general class documentation) + @internal + */ + static void * operator new[](std::size_t); + + /** not implemented (see general class documentation) + @internal + */ + static void operator delete[](void * pPtr); }; } -- cgit