/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ /* * The contents of this file are subject to the Mozilla Public * License Version 1.1 (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.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or * implied. See the License for the specific language governing * rights and limitations under the License. * * The Original Code is Mozilla. * * The Initial Developer of the Original Code is Netscape * Communications. Portions created by Netscape Communications are * Copyright (C) 2001 by Netscape Communications. All * Rights Reserved. * * Contributor(s): * Scott Collins (original author) */ #ifndef nsXPIDLString_h___ #define nsXPIDLString_h___ #ifndef nsSharableString_h___ #include "nsSharableString.h" #endif #if DEBUG_STRING_STATS #include #endif /** * Interface documentation: * * |nsXPIDLC?String| differs from |nsSharableC?String| in that one can * assign into it from an XPCOM getter that fills in a |char_type**| * with a pointer to a buffer whose ownership is to be transferred to * the caller. * * Consider the following interface: * * interface nsIFoo { * attribute string Bar; * }; * * This will generate the following C++ header file: * * class nsIFoo { * NS_IMETHOD SetBar(const PRUnichar* aValue); * NS_IMETHOD GetBar(PRUnichar* *aValue); * }; * * The GetBar() method will allocate a copy of the nsIFoo object's * "bar" attribute, and leave you to deal with freeing it: * * nsIFoo* aFoo; // assume we get this somehow * PRUnichar* bar; * aFoo->GetFoo(&bar); * do_something_with_buffer(bar); * nsMemory::Free(bar); * * This makes your life harder, because you need to convolute your * code to ensure that you don't leak `bar'. * * Enter nsXPIDLString, which manages the ownership of the allocated * string, and automatically destroys it when the nsXPIDLString goes * out of scope: * * nsIFoo* aFoo; // assume we get this somehow * nsXPIDLString bar; * aFoo->GetFoo( getter_Copies(bar) ); * do_something_with_buffer(bar.get()); * // no need to remember to nsMemory::Free(). * * Like nsCOMPtr, nsXPIDLString uses some syntactic sugar to make it * painfully clear exactly what the code expects. You need to wrap an * nsXPIDLString object with `getter_Copies()' before passing it to a * getter: these tell the nsXPIDLString how ownership is being * handled. * * In the case of `getter_Copies()', the callee is allocating a copy * (which is usually the case). In the case where the callee is * returning a const reference to `the real deal' (this can be done * using the [shared] attribute in XPIDL) you can just use a * |const char*| or |const PRUnichar*|. */ /** * Implementation notes: * * |nsXPIDLC?String| extends |nsSharableC?String| with the ability * to defer calculation of its length. This is crucial to allowing * the |getter_Copies| assignment behavior. * * The mechanism relies on the fact that |GetSharedBufferHandle| * must be called before any other object can share the buffer, * and as the default implementation for |GetBufferHandle|, which is * the operation on which all other flat string operations are based. * A valid handle will either have all |NULL| or all non-|NULL| * pointers. After use as an `out' string pointer parameter, an * |nsXPIDLC?String|'s handle will have a non-|NULL| data start, but * all other members will be |NULL|. This is the signal that the * length needs to be recalculated. |GetSharedBufferHandle| detects * this situation and repairs it. * * The one situation this _doesn't_ catch, is if no one ever tries to use * the string before it's destruction. In this case, because the start of * storage is known, storage can still be freed in the usual way. * * An |nsXPIDLC?String| is now a sharable object, just like * |nsSharableC?String|. * This simple implementation always allocates an intermediary handle * object. This cost might turn out to be a burden, it's something we'll * want to measure. A couple of optimizations spring to mind if allocation * of the handle objects shows up on the performance radar: * (1) introduce a custom allocator for the handles, e.g., keep free lists * or arena allocate them, or (2) fatten up the |nsXPIDLC?String| with a * local handle, and only allocate a shared handle in the event that * someone actually wants to share. Both of these alternatives add * complexity or space costs, and so we start with the simplest thing * that could possibly work :-) */ class NS_COM nsXPIDLString : public nsSharableString { public: typedef nsXPIDLString self_type; public: nsXPIDLString() : nsSharableString(GetSharedEmptyBufferHandle()) { #if DEBUG_STRING_STATS ++sCreatedCount; if ( ++sAliveCount > sHighWaterCount ) sHighWaterCount = sAliveCount; #endif } nsXPIDLString( const self_type& aString ) : nsSharableString(aString.mBuffer.get()) // copy-constructor required (or else C++ generates one for us) { #if DEBUG_STRING_STATS ++sCreatedCount; if ( ++sAliveCount > sHighWaterCount ) sHighWaterCount = sAliveCount; #endif } explicit nsXPIDLString( const abstract_string_type& aReadable ) : nsSharableString(aReadable) { #if DEBUG_STRING_STATS ++sCreatedCount; if ( ++sAliveCount > sHighWaterCount ) sHighWaterCount = sAliveCount; #endif } #if DEBUG_STRING_STATS ~nsXPIDLString() { --sAliveCount; } #endif self_type& operator=( const abstract_string_type& aReadable ) { Assign(aReadable); return *this; } /** * This is an override of a non-virtual function on * |nsSharableString|. This override is not necessary, but it can * improve performance in the case where we know we have an * |nsXPIDLString|. */ void Adopt( char_type* aNewValue ) { *PrepareForUseAsOutParam() = aNewValue; } // overridden to make getter_Copies mechanism work virtual const char_type* get() const { return (mBuffer.get() != GetSharedEmptyBufferHandle()) ? mBuffer->DataStart() : 0; } // deprecated, to be eliminated operator const char_type*() const { return get(); } char_type operator[]( int i ) const { return get()[ i ]; } class getter_Copies_t { public: getter_Copies_t( nsXPIDLString& aString ) : mString(&aString) { } // getter_Copies_t( const getter_Copies_t& ); // auto-generated copy-constructor OK // getter_Copies_t& operator=( const getter_Copies_t& ); // auto-generated assignment operator OK operator char_type**() const { return mString->PrepareForUseAsOutParam(); } private: nsXPIDLString* mString; }; friend class getter_Copies_t; protected: #if DEBUG_STRING_STATS virtual const buffer_handle_type* GetFlatBufferHandle() const; virtual const buffer_handle_type* GetBufferHandle() const; #endif virtual const shared_buffer_handle_type* GetSharedBufferHandle() const; // overridden to fix the length after `out' parameter assignment, if necessary char_type** PrepareForUseAsOutParam(); static shared_buffer_handle_type* GetSharedEmptyBufferHandle(); #if DEBUG_STRING_STATS static size_t sCreatedCount; // total number of |nsXPIDLString|s ever created static size_t sAliveCount; // total number of |nsXPIDLStrings|s alive right now static size_t sHighWaterCount; // greatest number of |nsXPIDLString|s alive at once static size_t sAssignCount; // total number of times |nsXPIDLString|s were // assigned into with |getter_Copies| static size_t sShareCount; // total number times |nsXPIDLString|s were asked to share public: static void DebugPrintStats( FILE* ); #endif }; inline nsXPIDLString::getter_Copies_t getter_Copies( nsXPIDLString& aString ) { return nsXPIDLString::getter_Copies_t(aString); } class NS_COM nsXPIDLCString : public nsSharableCString { public: typedef nsXPIDLCString self_type; public: nsXPIDLCString() : nsSharableCString(GetSharedEmptyBufferHandle()) { #if DEBUG_STRING_STATS ++sCreatedCount; if ( ++sAliveCount > sHighWaterCount ) sHighWaterCount = sAliveCount; #endif } nsXPIDLCString( const self_type& aString ) : nsSharableCString(aString.mBuffer.get()) // copy-constructor required (or else C++ generates one for us) { #if DEBUG_STRING_STATS ++sCreatedCount; if ( ++sAliveCount > sHighWaterCount ) sHighWaterCount = sAliveCount; #endif } #if DEBUG_STRING_STATS ~nsXPIDLCString() { --sAliveCount; } #endif self_type& operator=( const abstract_string_type& aReadable ) { Assign(aReadable); return *this; } /** * This is an override of a non-virtual function on * |nsSharableCString|. This override is not necessary, but it can * improve performance in the case where we know we have an * |nsXPIDLCString|. */ void Adopt( char_type* aNewValue ) { *PrepareForUseAsOutParam() = aNewValue; } // overridden to make getter_Copies mechanism work virtual const char_type* get() const { return (mBuffer.get() != GetSharedEmptyBufferHandle()) ? mBuffer->DataStart() : 0; } // deprecated, to be eliminated operator const char_type*() const { return get(); } char_type operator[]( int i ) const { return get()[ i ]; } class getter_Copies_t { public: getter_Copies_t( nsXPIDLCString& aString ) : mString(&aString) { } // getter_Copies_t( const getter_Copies_t& ); // auto-generated copy-constructor OK // getter_Copies_t& operator=( const getter_Copies_t& ); // auto-generated assignment operator OK operator char_type**() const { return mString->PrepareForUseAsOutParam(); } private: nsXPIDLCString* mString; }; friend class getter_Copies_t; protected: #if DEBUG_STRING_STATS virtual const buffer_handle_type* GetFlatBufferHandle() const; virtual const buffer_handle_type* GetBufferHandle() const; #endif virtual const shared_buffer_handle_type* GetSharedBufferHandle() const; // overridden to fix the length after `out' parameter assignment, if necessary char_type** PrepareForUseAsOutParam(); static shared_buffer_handle_type* GetSharedEmptyBufferHandle(); #if DEBUG_STRING_STATS static size_t sCreatedCount; // total number of |nsXPIDLCString|s ever created static size_t sAliveCount; // total number of |nsXPIDLCStrings|s alive right now static size_t sHighWaterCount; // greatest number of |nsXPIDLCString|s alive at once static size_t sAssignCount; // total number of times |nsXPIDLCString|s were // assigned into with |getter_Copies| static size_t sShareCount; // total number times |nsXPIDLCString|s were asked to share public: static void DebugPrintStats( FILE* ); #endif }; inline nsXPIDLCString::getter_Copies_t getter_Copies( nsXPIDLCString& aString ) { return nsXPIDLCString::getter_Copies_t(aString); } #endif /* !defined(nsXPIDLString_h___) */