sl@0: // Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32/include/e32shbufcmn.h
sl@0: // Shareable Data Buffers
sl@0: 
sl@0: /**
sl@0: 	@file
sl@0: 	@publishedPartner
sl@0: 	@prototype
sl@0: */
sl@0: 
sl@0: #ifndef E32SHBUFCMN_H
sl@0: #define E32SHBUFCMN_H
sl@0: 
sl@0: #include <e32shbuf_priv.h>
sl@0: #include <e32def.h>
sl@0: 
sl@0: /**
sl@0: 	Defines values used to modify client behaviour when opening a pool or buffer in a new process.
sl@0: 
sl@0: 	@publishedPartner
sl@0: 	@prototype
sl@0: */
sl@0: enum TShPoolHandleFlags
sl@0: 	{
sl@0: 	/**
sl@0: 	The buffers will be writeable in the process where this handle is used.
sl@0: 	If not set, the buffers will be read-only.
sl@0: 	*/
sl@0: 	EShPoolWriteable		= 0x0001,
sl@0: 
sl@0: 	/**
sl@0: 	The process will be able to allocate buffers from this pool.
sl@0: 	If not set, the process will not be able to allocate buffers from this pool.
sl@0: 	*/
sl@0: 	EShPoolAllocate			= 0x0002,
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: 	Defines flags for RShBuf::Alloc() and DShPool::Alloc().
sl@0: 
sl@0: 	@see RShBuf::Alloc()
sl@0: 	@see DShPool::Alloc()
sl@0: 
sl@0: 	@publishedPartner
sl@0: 	@prototype
sl@0: */
sl@0: enum TShPoolAllocFlags
sl@0: 	{
sl@0: 	/**
sl@0: 	The thread is willing to wait for a pool grow if no buffer is immediately available.
sl@0: 	If this is not set, the Alloc() will return immediately if no free buffer is available,
sl@0: 	but the pool might be able to grow to create new buffers.
sl@0: 	*/
sl@0: 	EShPoolAllocCanWait = 0x0001,
sl@0: 
sl@0: 	/**
sl@0: 	Do not automatically map the newly-allocated buffer into this process, if the pool is page-aligned.
sl@0: 	(RShBuf::Alloc() only.)
sl@0: 	*/
sl@0: 	EShPoolAllocNoMap = 0x0002,
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: 	Defines the attributes of a pool.
sl@0: 
sl@0: 	@publishedPartner
sl@0: 	@prototype
sl@0: */
sl@0: class TShPoolInfo
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C TShPoolInfo();
sl@0: 
sl@0: 	/**
sl@0: 	Specifies the size of each buffer in the pool.
sl@0: 	*/
sl@0: 	TUint iBufSize;
sl@0: 
sl@0: 	/**
sl@0: 	Specifies the initial number of buffers to be allocated to the pool.
sl@0: 	*/
sl@0: 	TUint iInitialBufs;
sl@0: 
sl@0: 	/**
sl@0: 	Specifies the maximum number of buffers the pool can grow to.
sl@0: 	*/
sl@0: 	TUint iMaxBufs;
sl@0: 
sl@0: 	/**
sl@0: 	This specifies when the pool grows.  If zero, the pool will not grow or shrink
sl@0: 	automatically.
sl@0:   
sl@0: 	This is the proportion of free buffers left in the pool at which it should be grown.
sl@0: 	For example, if the ratio is 0.1, the pool will be grown when the number of free
sl@0: 	buffers drops to 10%.
sl@0: 
sl@0: 	This value is expressed as a 32-bit fixed-point number, where the binary
sl@0: 	point is defined to be between bits 7 and 8 (where the least-significant
sl@0: 	bit is defined as bit 0).  (This format is also known as a Q8, or fx24.8
sl@0: 	number, or alternatively as the value * 256.)  For the example given of 10%,
sl@0: 	use the value 26.  It represents a value < 1 (i.e. must be < 256).  Calculations
sl@0: 	are rounded down towards zero, but if calculating how many buffers to trigger
sl@0: 	on gives 0, the grow will be triggered when 1 buffer is free.
sl@0: 	*/
sl@0: 	TUint iGrowTriggerRatio;
sl@0: 
sl@0: 	/**
sl@0: 	This specifies the proportion by which to grow the pool each time it is grown.
sl@0: 	If zero, the pool will not grow or shrink automatically.
sl@0: 
sl@0: 	It is expressed as a 32-bit fx24.8 fixed-point number, in the same way as
sl@0: 	iGrowTriggerRatio.  Calculations are rounded down towards zero, but if calculating
sl@0: 	how many buffers to grow by yields 0, then the pool will be grown by 1 buffer.
sl@0: 	*/
sl@0: 	TUint iGrowByRatio;
sl@0: 
sl@0: 	/**
sl@0: 	The hysteresis value to ensure that the pool does not automatically shrink
sl@0: 	immediately after is grows.
sl@0: 
sl@0: 	Automatic shrinking will only happen when there are (iGrowTriggerRatio +
sl@0: 	iGrowByRatio) * iShrinkHysteresisRatio * (total buffers in the pool) free
sl@0: 	buffers left in the pool.
sl@0: 
sl@0: 	The amount by which the pool is shrunk depends on iGrowByRatio: it is the operational
sl@0: 	inverse, such that the pool would shrink down to the same number of buffers if shrunk
sl@0: 	immediately after growing (although hysteresis normally prevents this).
sl@0: 
sl@0: 	For example, if iGrowByRatio is 10%, a pool of 100 buffers would grow to 110 buffers.
sl@0: 	To shrink back to 100, a shrink ratio of 10/110 = 9% is required.  That is, if the
sl@0: 	grow-by ration is G, the shrink-by ratio S is calculated as S = 1 - 1 / (1 + G).
sl@0: 
sl@0: 	iShrinkHysteresisRatio is a 32-bit fx24.8 fixed-point number in the same way as
sl@0: 	iGrowTriggerRatio and iGrowByRatio.  It represents a value > 1 (i.e. must be > 256).
sl@0: 
sl@0: 	@see iGrowByRatio
sl@0: 	*/
sl@0: 	TUint iShrinkHysteresisRatio;
sl@0: 
sl@0: 	/**
sl@0: 	Specifies the alignment for each buffer, as a shift count (log2 bytes).
sl@0: 
sl@0: 	For example, 9 means that each buffer is aligned on a 512-byte boundary.
sl@0: 	*/
sl@0: 	TUint iAlignment;
sl@0: 
sl@0: 	/**
sl@0: 	Specifies flags for the pool, as bit values from TShPoolCreateFlags or-ed together.
sl@0: 
sl@0: 	@see TShPoolCreateFlags
sl@0: 	*/
sl@0: 	TUint iFlags;
sl@0: private:
sl@0: 	TInt iSpare1;			// Reserved for future use
sl@0: 	TInt iSpare2;
sl@0: 	TInt iSpare3;
sl@0: 	TInt iSpare4;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: #endif	// E32SHBUF_H
sl@0: