// 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 "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: Implementation of system shared buffer allocation and buffer
// management.
//

#ifndef __SYSTEMSHAREDBUFS_H__
#define __SYSTEMSHAREDBUFS_H__

#include "commsbufpondintf.h"
#include "commsbufponddbg.h"
#include "commsbufpool.h"
#include "systemsharedasyncalloc.h"
#include "commsbufq.h"
#include "commsbufponddbg.h"
#include <e32shbuf.h>

class TCommsBufPoolCreateInfo;
class RCommsBuf;
class RShPool;
class MCommsBufPondIntf;
/**

Representation of a single system shared pool.Allocates/free from the system shared pool or from 
the freelist if enabled) 

@internalTechnology
 
*/
NONSHARABLE_CLASS(CSystemSharedBufPool) : public CCommsBufPool
	{
	public:
	static CSystemSharedBufPool* New(MCommsBufPondIntf& aPondIntf, const TCommsBufPoolCreateInfo& aCreateInfo);
	
#ifdef  SYMBIAN_ZEROCOPY_BUF_FREELIST
	TInt FreeListCount();
#endif // SYMBIAN_ZEROCOPY_BUF_FREELIST
	
	~CSystemSharedBufPool();
	
	TInt AllocUnderflow(RCommsBufQ& aBufQ, TInt aSize);	
	TInt AllocOverflow(RCommsBufQ& aBufQ, TInt aSize);
	
	RCommsBuf* Alloc();
	void Free(RCommsBuf* aBuf);
	inline RShPool Pool() const;

	static TInt Compare(const CSystemSharedBufPool& aLhs, const CSystemSharedBufPool& aRhs);	

	private:
	inline CSystemSharedBufPool(MCommsBufPondIntf& aPondIntf, TInt aSize);
    TInt Construct(const TCommsBufPoolCreateInfo& aCreateInfo); 
    
#ifdef	SYMBIAN_ZEROCOPY_BUF_FREELIST
	inline CSystemSharedBufPool(MCommsBufPondIntf& aPondIntf, TInt aSize, TInt aFreeListCount);	
	TInt AllocFromFreeList(RCommsBufQ& BufQ, TInt aSize);
	TBool ReleaseToFreeList(RCommsBuf* aBuf); 
#endif // SYMBIAN_ZEROCOPY_BUF_FREELIST
	
	private:
	RShPool		iPool;
#ifdef SYMBIAN_ZEROCOPY_BUF_FREELIST
	RWorkerLock iFreeListLock;
	RCommsBufQ  iFreeList;
	TInt        iMaxFreeListCount;
	TInt        iFreeListCount;
#endif // SYMBIAN_ZEROCOPY_BUF_FREELIST
	};

/**
Implements the 3 stage buffer allocation algorithm using the system wide shared buffer APIs or
from the freelist (if enabled)

Description of the 3 stage allocator.

Requirements:
1/ The algorithm MUST try to allocate from the pool that has bigger or equal size buffers in 
preference to the pools that has smaller size buffers ie; 
2/ The algorithm MUST return fewest bytes of memory that satisfy the request and doesn't conflict 
with 1/
3/ More than one buffer may be allocated and linked, if the requested buffer size doesn't directly 
satisfy with the configured buffer sizes.

Input parameters:
Size            - Requested total size 
Minimum Size    - The size that the allocated buffer(s) must atleast have                       
Maximum Size    - The size that the allocated buffer(s) must not exceed     
            

Working Model:
The algorithm relies on the big to small order. If the order is not obeyed/adhered the algorithm will 
fail to allocate the buffers from the right pools and more buffers maybe allocated than needed.The 
pools are sorted during initialization time.        

The first step in the algorithm is to clip the pool array position based on the given min and max size. 
Clipping is done to ensure that allocation happens from the pools that satisfies the given min and 
max condition, and no further checking is needed on the pools to see whether the pool buffer size 
satisfies the min and max values. Once the clipping is done the algorithm works in 4 stages.   

The following terms are used in the description of the algorithm. The terms should be read as:
biggest pool ---  The pool that has the bigger buffer size, relative to the given max value
smallest pool --- The pool that has the smallest buffer size, relative to the given min value 

The reader should note that there is no gurantee that the requested allocation size will be exactly or 
nearly matching to the pool sizes and this applies to each stage that operatea on the allocation size.
 
The first stage execution depends on the input parameters and lower and upper index. Subsequent stages 
exectuion depend on the outcome of the prior stage.
    
The 4 stages are:
1/ Traverse the pool array forward from the biggest pool index till the traversal reaches the smallest 
pool index. When the requested size is greater than the buffer size of the "next" pool allocate as much 
as possible from the "current" pool and decrement the requested size if there is an allocation. If there 
is no allocation happens from the "current" pool mark the "current" pool index and exit the stage.
 At this point,
 a/ We allocated completely as requested or 
 b/ We would have been passed through and didn't allocate from the bigger pools that may have buffer for 
 allocation in order to satisfy the Credo 2/. But we MUST satisfy the Credo 1/ and in order to satisfy the 
 Credo 1/ we need to traverse back from the point where we stopped the traversal, hence need to mark the 
 "current" pool index. 
2/ If the first stage allocation cannot complete due to the non-availability of buffer in the pools or with 
1.b/ traverse the array backward starting from the marked pool index till the traversal reaches the biggest 
pool index. Allocate from any pool where buffers are available by satisfying Credo 1/.
3/ If the second stage allocation cannot complete due to the non-availability of buffers then we have to 
increment the marked pool index by 1 as the marked pool has been checked for buffer availability on the 2nd 
stage. We have the following scenario:
 a/ The pending allocation size (maybe partial or the size "actually" requested)is greater than the marked 
 pool index buffer size
 b/ Allocation MUST satisfy the Credo 1/

Traverse the array forward from the marked pool index till the traversal reaches the smallest pool index. 
Allocate from any pool where buffers are available.   

Special condition:
If the requested size is 0 we will allocate from the pool that has the smallest buffer size, provided the
availability of buffers in the pool. The zero sized allocation takes a different path (using ZeroSizedAlloc Fn.)
and does not run through the stages as described above.

Reasoning:

We MUST satisfy the requirement 1 and we SHOULD try to achieve the requirement 2 then we have the following 
that we encounter during allocation

1/ No gurantee that we get buffers from the pool that has the best size for the allocation.
2/ We might skip a pool to identify the more best size and we may not be able to allocate from that pool
due to the non-availablity of the buffers. We would be needing to traverse back on the pool array.
3/ No gurantee that we can allocate we traverse back because some other threads woule have been executed inbetween
and allocate the buffers and the pool might became empty. and vice versa.

Drawbacks:

1/ More looping happens with the algorithm on certain cases when the bigger size pools became empty.

Conclusion:
1/ Couple of more loops on certain cases does not add much problems as the total no. of elements in the pools   
are expected to be ~10 hence does not cause much problems in terms of performance.
2/ All depends on how the pool buffer sizes are configured. It is expected that the smaller size buffer numbers 
in the pool will be lesser than bigger sizes. So most time we get good allocation.
3/ More problems are on the allocation of system shared buffer from the Kernal as the algorithm has to allocate
one by one and ask the pool each time. If there is no buffers available on the requested pool there will be more 
system calls 

Based on the above arguments the conclusion is that algorithm (and the couple of more loops) doesn't cause much 
problems


Future & suggestions:
It maybe possible to fine tune the algorithm. But any futuer enhancements should consider 
1/ the min and max  conditions
2/ Non-deterministic configured pool sizes

One of the thing that would definitly improve the algorithm is to request the kernel to allocate a series of
RShBuf's. This would reduce the no. of system calls that is currently happening on the system. The current freelist
implementation tries to address this issue to an extent.

@internalTechnology
*/

class T3StageAllocator
	{
	public:
	    T3StageAllocator(RPointerArray<CSystemSharedBufPool>& aPools, TInt aSize, TInt aMinSize, TInt aMaxSize);
	RCommsBuf* Do();
	
	private:
	
	void Init(TInt aMinSize, TInt aMaxSize);
	
	void ForwardAlloc1stStage();
	void BackwardAlloc2ndStage();
	void ForwardAlloc3rdStage();
	
	void ZeroSizedAlloc();
	
	private:
	RPointerArray<CSystemSharedBufPool>& iPools;
	TInt iSize;
	TInt iBiggestPoolIndex;
	TInt iSmallestPoolIndex;
	TInt iMarkedPoolIndex;	
	RCommsBufQ iBufQ;
	TBool iZeroBufSize;	
	};

/**
Implements the buffer management using the system wide shared buffers

@internalTechnology
*/
NONSHARABLE_CLASS(CSystemSharedBufPond) : public CBase, public MCommsBufPondIntf, public MCommsBufPondDbg
	{
	friend class RCommsBufPond;

	public:
	static MCommsBufPondIntf* New(RArray <TCommsBufPoolCreateInfo>& aPoolInfo);
	~CSystemSharedBufPond();
	
	private:
	
	TInt Construct(RArray <TCommsBufPoolCreateInfo>& aPoolInfo);

	// From MCommsBufPondIntf
	virtual RCommsBuf* Alloc(TInt aSize, TInt aMinBufSize, TInt aMaxBufSize);
	virtual RCommsBuf* FromHandle(TInt aHandle);
	virtual TInt Store(TDes8& aStore) const;
	virtual void Free(RCommsBuf* aBuf);
	virtual TInt BytesAvailable() const;
	virtual TInt BytesAvailable(TInt aSize) const;
	virtual TInt NextBufSize(TInt aSize) const;
	virtual TInt LargestBufSize() const;
	virtual void StartRequest(CCommsBufAsyncRequest& aRequest);
	virtual void CancelRequest(CCommsBufAsyncRequest& aRequest);
	virtual void SetContext();
	virtual void Release(RLibrary& aLib);
	virtual MCommsBufPondDbg& CommsBufPondDbg();

	// From MCommsBufPondDbg
    virtual RCommsBuf* __DbgBufChain();
    virtual RCommsBuf* __DbgBufChain(TUint aBufSize);
    virtual void __DbgSetPoolLimit(TInt aCount);
    virtual void __DbgSetPoolLimit(TInt aCount, TUint aBufSize);
    virtual void __DbgSetFailAfter(TInt aCount=0);
    virtual TUint __DbgGetBufSpace();
    virtual TUint __DbgGetBufSpace(TUint aBufSize);
    virtual TUint __DbgGetBufTotal();
    virtual TUint __DbgGetBufTotal(TUint aMufSize);
    virtual TInt __DbgGetHeapSize();

	private:
	RPointerArray<CSystemSharedBufPool> iPools;
	CSystemSharedAsyncAlloc*			iAsyncAlloc;
  	};

#include "systemsharedbufs.inl"
#endif // __SYSTEMSHAREDBUFS_H__