1 // Copyright (c) 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 the License "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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // e32/include/e32shbufcmn.h
15 // Shareable Data Buffers
26 #include <e32shbuf_priv.h>
30 Defines values used to modify client behaviour when opening a pool or buffer in a new process.
35 enum TShPoolHandleFlags
38 The buffers will be writeable in the process where this handle is used.
39 If not set, the buffers will be read-only.
41 EShPoolWriteable = 0x0001,
44 The process will be able to allocate buffers from this pool.
45 If not set, the process will not be able to allocate buffers from this pool.
47 EShPoolAllocate = 0x0002,
52 Defines flags for RShBuf::Alloc() and DShPool::Alloc().
60 enum TShPoolAllocFlags
63 The thread is willing to wait for a pool grow if no buffer is immediately available.
64 If this is not set, the Alloc() will return immediately if no free buffer is available,
65 but the pool might be able to grow to create new buffers.
67 EShPoolAllocCanWait = 0x0001,
70 Do not automatically map the newly-allocated buffer into this process, if the pool is page-aligned.
71 (RShBuf::Alloc() only.)
73 EShPoolAllocNoMap = 0x0002,
78 Defines the attributes of a pool.
86 IMPORT_C TShPoolInfo();
89 Specifies the size of each buffer in the pool.
94 Specifies the initial number of buffers to be allocated to the pool.
99 Specifies the maximum number of buffers the pool can grow to.
104 This specifies when the pool grows. If zero, the pool will not grow or shrink
107 This is the proportion of free buffers left in the pool at which it should be grown.
108 For example, if the ratio is 0.1, the pool will be grown when the number of free
109 buffers drops to 10%.
111 This value is expressed as a 32-bit fixed-point number, where the binary
112 point is defined to be between bits 7 and 8 (where the least-significant
113 bit is defined as bit 0). (This format is also known as a Q8, or fx24.8
114 number, or alternatively as the value * 256.) For the example given of 10%,
115 use the value 26. It represents a value < 1 (i.e. must be < 256). Calculations
116 are rounded down towards zero, but if calculating how many buffers to trigger
117 on gives 0, the grow will be triggered when 1 buffer is free.
119 TUint iGrowTriggerRatio;
122 This specifies the proportion by which to grow the pool each time it is grown.
123 If zero, the pool will not grow or shrink automatically.
125 It is expressed as a 32-bit fx24.8 fixed-point number, in the same way as
126 iGrowTriggerRatio. Calculations are rounded down towards zero, but if calculating
127 how many buffers to grow by yields 0, then the pool will be grown by 1 buffer.
132 The hysteresis value to ensure that the pool does not automatically shrink
133 immediately after is grows.
135 Automatic shrinking will only happen when there are (iGrowTriggerRatio +
136 iGrowByRatio) * iShrinkHysteresisRatio * (total buffers in the pool) free
137 buffers left in the pool.
139 The amount by which the pool is shrunk depends on iGrowByRatio: it is the operational
140 inverse, such that the pool would shrink down to the same number of buffers if shrunk
141 immediately after growing (although hysteresis normally prevents this).
143 For example, if iGrowByRatio is 10%, a pool of 100 buffers would grow to 110 buffers.
144 To shrink back to 100, a shrink ratio of 10/110 = 9% is required. That is, if the
145 grow-by ration is G, the shrink-by ratio S is calculated as S = 1 - 1 / (1 + G).
147 iShrinkHysteresisRatio is a 32-bit fx24.8 fixed-point number in the same way as
148 iGrowTriggerRatio and iGrowByRatio. It represents a value > 1 (i.e. must be > 256).
152 TUint iShrinkHysteresisRatio;
155 Specifies the alignment for each buffer, as a shift count (log2 bytes).
157 For example, 9 means that each buffer is aligned on a 512-byte boundary.
162 Specifies flags for the pool, as bit values from TShPoolCreateFlags or-ed together.
164 @see TShPoolCreateFlags
168 TInt iSpare1; // Reserved for future use