My first commit on the Symbian Hg repository. Testng how branches are working.
// Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
// All rights reserved.
// This component and the accompanying materials are made available
// under the terms of the License "Eclipse Public License v1.0"
// which accompanies this distribution, and is available
// at the URL "http://www.eclipse.org/legal/epl-v10.html".
//
// Initial Contributors:
// Nokia Corporation - initial contribution.
//
// Contributors:
//
// Description:
// e32/include/e32shbuf.h
// Shareable Data Buffers
/**
@file
@publishedPartner
@prototype
*/
#ifndef E32SHBUF_H
#define E32SHBUF_H
#include <e32shbufcmn.h>
#include <e32cmn.h>
/**
Specifies characteristics of the pool to be created.
@see RShPool::Create()
@publishedPartner
@prototype
*/
class TShPoolCreateInfo
{
public:
/**
Enumeration type to create a pool with page-aligned buffers.
The buffers in the pool will be at least the size of an MMU page,
aligned to an MMU page, and may be mapped in and out of a process's
address space independently.
*/
enum TShPoolPageAlignedBuffers
{
EPageAlignedBuffer = EShPoolPageAlignedBuffer,
};
/**
Enumeration type to create a pool with non-page-aligned buffers.
The buffers in the pool do not have any size or alignment restrictions beyond
the iAlignment specified in TShPoolInfo.
The whole pool will always mapped into a process's address space.
*/
enum TShPoolNonPageAlignedBuffers
{
ENonPageAlignedBuffer = EShPoolNonPageAlignedBuffer,
};
/**
Specifies the buffer size and initial number of committed buffers for a pool
with page-aligned buffers.
@param aFlag Page-aligned buffers
@param aBufSize Size in bytes of each buffer within the pool
@param aInitialBufs Initial number of buffers allocated to the pool
*/
IMPORT_C TShPoolCreateInfo(TShPoolPageAlignedBuffers aFlag, TUint aBufSize, TUint aInitialBufs);
/**
Specifies the buffer size, initial number of committed buffers, and buffer
alignment for a pool with non-page-aligned buffers.
@param aFlag Non-page aligned buffers
@param aBufSize Size in bytes of each buffer within the pool
@param aInitialBufs Initial number of buffers allocated to the pool
@param aAlignment Alignment of the start of each buffer in the pool (shift/log2 value)
*/
IMPORT_C TShPoolCreateInfo(TShPoolNonPageAlignedBuffers aFlag, TUint aBufSize, TUint aInitialBufs, TUint aAlignment);
/**
Sets the sizing attributes for the pool, allowing it to grow and
shrink automatically.
If either aGrowTriggerRatio or aGrowByRatio is 0, no automatic growing or
shrinking will be performed.
@param aMaxBufs The maximum number of buffers that the pool
can grow to. This value must not be less than
aInitialBufs.
@param aGrowTriggerRatio This specifies when to grow the pool. When the
proportion of free buffers in the pool drops below
this value, the pool will be grown. This value is
expressed as a 32-bit fixed-point number, where
the binary point is defined to be between bits
7 and 8 (where the least-significant bit is defined
as bit 0). (This format is also known as a Q8, or
fx24.8 number, or alternatively as the value * 256.)
It must represent a value < 1 (i.e. must be < 256).
@param aGrowByRatio The proportion to grow the pool by each time,
expressed as a 32-bit fx24.8 fixed-point number, in
the same way as aGrowTriggerRatio.
@param aShrinkHysteresisRatio The hysteresis value to ensure that a pool is not
automatically shrunk immediately after it is grown.
Automatic shrinking will only happen when there are
(aGrowTriggerRatio + aGrowByRatio) * aShrinkHysteresisRatio *
(total buffers in the pool) free buffers left in the pool.
This is a 32-bit fx24.8 fixed-point number in the
same way as aGrowTriggerRatio and aGrowByRatio.
It must represent a value > 1 (i.e. must be > 256).
*/
IMPORT_C TInt SetSizingAttributes(TUint aMaxBufs, TUint aGrowTriggerRatio,
TUint aGrowByRatio, TUint aShrinkHysteresisRatio);
/**
Ensures that each buffer is mapped into at most one process address space
at a time.
If this is set for a non-page-aligned pool, the pool creation will fail.
*/
IMPORT_C TInt SetExclusive();
/**
Specifies that unmapped guard pages are inserted between each buffer in a process's
address space.
If this is set for a non-page-aligned pool, the pool creation will fail.
*/
IMPORT_C TInt SetGuardPages();
private:
friend class RShPool;
TShPoolCreateInfo(); // hide the default constructor
TShPoolInfo iInfo;
};
/**
A handle to a pool of buffers.
Pools can be created by either user-side or kernel-side components.
Upon receiving a pool handle the recipient must map either whole or part of the pool
memory into its address space.
When finished with the pool, the recipient must Close() it: this invalidates the handle.
Any further attempt to use it will panic the thread.
All pools are reference-counted and will only disappear after all users have closed them.
These handles are process-relative.
@publishedPartner
@prototype
*/
class RShPool : public RHandleBase
{
public:
IMPORT_C RShPool();
/**
Creates a pool of buffers with the required attributes and maps the memory to this process.
The RShPool object is changed by this call (iHandle is set).
@param aBufInfo A structure describing the parameters of the pool to be created.
See TShPoolCreateInfo.
@param aFlags Flags to modify the behaviour of the handle. This should be a bit-wise
OR of values from TShPoolHandleFlags.
@return the handle (>= 0) if successful, otherwise one of the system-wide error codes.
@see TShPoolCreateInfo
@see TShPoolClientFlags
*/
IMPORT_C TInt Create(const TShPoolCreateInfo& aBufInfo, TUint aFlags);
/**
Retrieves information about the pool.
@param aInfo returns pool info.
*/
IMPORT_C void GetInfo(TShPoolInfo& aInfo) const;
/**
Specifies how many buffers of a page-aligned pool this process will require
concurrent access to.
This determines how much of the process's address space will be allocated for
buffers of this pool.
@param aCount Specifies the number of buffers to map into the process's virtual address space
(-1 specifies that all buffers will be mapped).
@param aAutoMap ETrue specifies that an allocated or received buffer
will be automatically mapped into the process's address space.
@pre the pool's buffers must be page-aligned
@return KErrNone if successful, otherwise one of the system-wide error codes.
*/
IMPORT_C TInt SetBufferWindow(TInt aCount, TBool aAutoMap);
/**
@return the number of free buffers in the pool
*/
IMPORT_C TUint FreeCount() const;
/**
Requests a notification when the number of free buffers in the pool falls to the
level specified.
@param aFreeBuffers Specifies the number of free buffers that will trigger completion of the notification.
@param aStatus Status request to be completed when the condition is met.
*/
IMPORT_C void RequestLowSpaceNotification(TUint aFreeBuffers, TRequestStatus& aStatus);
/**
Requests a notification when the number of free buffers in the pool rises to the
level specified.
@param aFreeBuffers Specifies the number of free buffers that will trigger completion of the notification.
@param aStatus Status request to be completed when the condition is met.
*/
IMPORT_C void RequestFreeSpaceNotification(TUint aFreeBuffers, TRequestStatus& aStatus);
/**
Cancels a low space notification request.
The status request completes with KErrCancel.
@param aStatus The status request whose notification is to be cancelled.
*/
IMPORT_C void CancelLowSpaceNotification(TRequestStatus& aStatus);
/**
Cancels a free space notification request.
The status request completes with KErrCancel.
@param aStatus The status request whose notification is to be cancelled.
*/
IMPORT_C void CancelFreeSpaceNotification(TRequestStatus& aStatus);
};
/**
A handle to a shared buffer within a pool.
A user-side or kernel-side component allocates the buffer and then passes the
handle to the recipient.
Upon receiving a buffer handle. the recipient may map the buffer memory into its address space if not already done so.
When finished with the buffer, the recipient must Close() the handle. This
invalidates the handle; any further attempt to use it will panic the thread.
Buffers are reference-counted and will only be freed and returned to the pool
when all users have closed them.
These handles are process-relative.
@publishedPartner
@prototype
*/
class RShBuf : public RHandleBase
{
public:
inline RShBuf() : iBase(0), iSize(0) {};
IMPORT_C void Close();
/**
Allocates a shared data buffer.
By default this method will return immediately with KErrNoMemory if no buffer is
available on the pool's free list, even if the pool could grow automatically.
By default it will also map the allocated buffer into the calling process's address space.
Setting EShPoolAllocCanWait in the flags indicates that the caller is prepared to
wait while the pool is grown if a buffer is not immediately available on the free list.
Setting EShPoolAllocNoMap in the flags indicates that the caller does not want the
buffer to be automatically mapped into its address space. This can improve performance
on buffers from page-aligned pools if the caller will not need to access the data in the
buffer (e.g. if it will just be passing it on to another component). This only prevents
mapping if the pool is set to not automatically map buffers into processes' address space.
@param aPool Pool handle
@param aFlags Bitwise OR of values from TShPoolAllocFlags to specify non-default behaviour.
@return KErrNone if successful, otherwise one of the system-wide error codes.
@see TShPoolAllocFlags
*/
IMPORT_C TInt Alloc(RShPool& aPool, TUint aFlags = 0);
/**
Maps the buffer into the calling process's virtual address space if not already done.
It is not necessary to call this method on buffers from non-page-aligned pools, although
it will cause no harm to do so (and will result in KErrNone being returned).
It is not necessary to call this method on buffers from page-aligned pools returned by
Alloc() unless EShPoolAllocNoMap was specified.
@param aReadOnly Indicates whether the buffer should be mapped as read-only. The default is
that of pool in the clients address space.
@return KErrNone if successful, otherwise one of the system-wide error codes.
*/
IMPORT_C TInt Map(TBool aReadOnly = EFalse);
/**
Unmaps the buffer from the calling process's virtual address space.
@return KErrNone if successful, otherwise one of the system-wide error codes.
*/
IMPORT_C TInt UnMap();
/**
@return The size, in bytes, of this buffer (and every other buffer in the pool).
*/
IMPORT_C TUint Size();
/**
@return A pointer to the start of the buffer.
*/
IMPORT_C TUint8* Ptr();
private:
friend class RShPool;
TLinAddr iBase;
TUint iSize;
TUint iSpare1;
TUint iSpare2;
};
#endif // E32SHBUF_H