зеркало из https://github.com/mozilla/gecko-dev.git
361 строка
12 KiB
C++
361 строка
12 KiB
C++
/* -*- 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 <scc@mozilla.org> (original author)
|
|
*/
|
|
|
|
#ifndef nsXPIDLString_h___
|
|
#define nsXPIDLString_h___
|
|
|
|
#ifndef nsSharableString_h___
|
|
#include "nsSharableString.h"
|
|
#endif
|
|
|
|
#if DEBUG_STRING_STATS
|
|
#include <stdio.h>
|
|
#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___) */
|