1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #ifndef __VERSITTLS_H__

    17 #define __VERSITTLS_H__

    18 

    19 // System includes

    20 #include <e32base.h>

    21 #include <charconv.h>

    22 

    23 #include <vutil.h>

    24 

    25 class CVersitTimer;

    26 class CVersitAdditionalStorage;

    27 

    28 class CVersitTlsData : public CBase

    29 /** Versit thread local storage.

    30 

    31 This class provides a performance improvement by allowing a CVersitUnicodeUtils 

    32 instance to be shared between parsers operating in the same thread, so that 

    33 a new instance does not have to be created for each parser. A pointer to the 

    34 unicode utilities object is held in thread local storage: a single word (32bits) 

    35 of data. Each unicode utilities object is managed by an instance of this class.

    36 

    37 Every time a parser is created, CVersitParser::ConstructL() calls the 

    38 CVersitTlsData constructor, and when the parser is destroyed the CVersitTlsData 

    39 destructor is called. If a CVersitTlsData object exists, the constructor 

    40 returns a pointer to it, otherwise a new one is constructed. The CVersitTlsData 

    41 object is only destroyed when no more parsers refer to it: a count is kept, 

    42 which is incremented every time the constructor is called and decremented each 

    43 time the destructor is called, and the object is only destroyed when the count 

    44 reaches zero.

    45 

    46 This class provides an additional major performance improvement 

    47 if you are sequentially constructing and destructing multiple parsers. 

    48 By default, when the count of parsers reaches zero, the thread local 

    49 storage object is destroyed (even if the thread has not finished). However, 

    50 by using the technique described below, the thread local storage object, and therefore 

    51 the unicode utilities object, can be made to persist, significantly reducing 

    52 the overhead of sequentially constructing and destructing parsers.

    53 

    54 The constructor needs to be called an extra time before creating any parsers, 

    55 and the destructor needs to be called an extra time once the parsers have 

    56 been destroyed. This has the effect of adding one to the reference count so 

    57 that during all the parser construction and deletion the count never hits 

    58 zero, which would trigger the TLS object's destruction.

    59 

    60 This can be implemented as follows:

    61 

    62 1. Create a thread local storage data class instance as follows: 

    63 @code

    64 CVersitTlsData* versitTLS = CVersitTlsData::VersitTlsDataL(); 

    65 @endcode

    66 

    67 2. Create and delete the parsers. 

    68 

    69 3. Delete the Thread Local Storage Data class instance: 

    70 @code

    71 delete versitTLS; 

    72 @endcode 

    73 @publishedAll

    74 @released

    75 */

    76 	{

    77 	friend class CVersitTimer;

    78 

    79 public:

    80 	IMPORT_C static CVersitTlsData& VersitTlsDataL();

    81 	IMPORT_C static void CloseVersitTlsData();

    82 	IMPORT_C void VersitTlsDataClose();

    83 

    84 public:

    85 	inline CVersitUnicodeUtils& UnicodeUtils() 

    86 	/** Returns a pointer to the current Unicode utilities object.

    87 	

    88 	@return A pointer to the current Unicode utilities object. */

    89 		{ return *iUnicodeUtils; }

    90 

    91     inline CVersitAdditionalStorage& AdditionalStorage()

    92 	/** Returns a pointer to the additional property storage object.

    93 	

    94 	@return A pointer to the additional property storage. */

    95         {

    96         return *iAdditionalStorage;

    97         }

    98 

    99 private:

   100 	static CVersitTlsData* NewL();

   101 	void ConstructL();

   102 	~CVersitTlsData();

   103 

   104 private:

   105 	TInt iRefCount;

   106 	CVersitUnicodeUtils* iUnicodeUtils;

   107     CVersitAdditionalStorage* iAdditionalStorage;

   108 	};

   109 

   110 #endif