|
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 "Symbian Foundation License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // e32/include/e32shbufcmn.h |
|
15 // Shareable Data Buffers |
|
16 |
|
17 /** |
|
18 @file |
|
19 @publishedPartner |
|
20 @prototype |
|
21 */ |
|
22 |
|
23 #ifndef E32SHBUFCMN_H |
|
24 #define E32SHBUFCMN_H |
|
25 |
|
26 #include <e32shbuf_priv.h> |
|
27 #include <e32def.h> |
|
28 |
|
29 /** |
|
30 Defines values used to modify client behaviour when opening a pool or buffer in a new process. |
|
31 |
|
32 @publishedPartner |
|
33 @prototype |
|
34 */ |
|
35 enum TShPoolHandleFlags |
|
36 { |
|
37 /** |
|
38 The buffers will be writeable in the process where this handle is used. |
|
39 If not set, the buffers will be read-only. |
|
40 */ |
|
41 EShPoolWriteable = 0x0001, |
|
42 |
|
43 /** |
|
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. |
|
46 */ |
|
47 EShPoolAllocate = 0x0002, |
|
48 }; |
|
49 |
|
50 |
|
51 /** |
|
52 Defines flags for RShBuf::Alloc() and DShPool::Alloc(). |
|
53 |
|
54 @see RShBuf::Alloc() |
|
55 @see DShPool::Alloc() |
|
56 |
|
57 @publishedPartner |
|
58 @prototype |
|
59 */ |
|
60 enum TShPoolAllocFlags |
|
61 { |
|
62 /** |
|
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. |
|
66 */ |
|
67 EShPoolAllocCanWait = 0x0001, |
|
68 |
|
69 /** |
|
70 Do not automatically map the newly-allocated buffer into this process, if the pool is page-aligned. |
|
71 (RShBuf::Alloc() only.) |
|
72 */ |
|
73 EShPoolAllocNoMap = 0x0002, |
|
74 }; |
|
75 |
|
76 |
|
77 /** |
|
78 Defines the attributes of a pool. |
|
79 |
|
80 @publishedPartner |
|
81 @prototype |
|
82 */ |
|
83 class TShPoolInfo |
|
84 { |
|
85 public: |
|
86 IMPORT_C TShPoolInfo(); |
|
87 |
|
88 /** |
|
89 Specifies the size of each buffer in the pool. |
|
90 */ |
|
91 TUint iBufSize; |
|
92 |
|
93 /** |
|
94 Specifies the initial number of buffers to be allocated to the pool. |
|
95 */ |
|
96 TUint iInitialBufs; |
|
97 |
|
98 /** |
|
99 Specifies the maximum number of buffers the pool can grow to. |
|
100 */ |
|
101 TUint iMaxBufs; |
|
102 |
|
103 /** |
|
104 This specifies when the pool grows. If zero, the pool will not grow or shrink |
|
105 automatically. |
|
106 |
|
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%. |
|
110 |
|
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. |
|
118 */ |
|
119 TUint iGrowTriggerRatio; |
|
120 |
|
121 /** |
|
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. |
|
124 |
|
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. |
|
128 */ |
|
129 TUint iGrowByRatio; |
|
130 |
|
131 /** |
|
132 The hysteresis value to ensure that the pool does not automatically shrink |
|
133 immediately after is grows. |
|
134 |
|
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. |
|
138 |
|
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). |
|
142 |
|
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). |
|
146 |
|
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). |
|
149 |
|
150 @see iGrowByRatio |
|
151 */ |
|
152 TUint iShrinkHysteresisRatio; |
|
153 |
|
154 /** |
|
155 Specifies the alignment for each buffer, as a shift count (log2 bytes). |
|
156 |
|
157 For example, 9 means that each buffer is aligned on a 512-byte boundary. |
|
158 */ |
|
159 TUint iAlignment; |
|
160 |
|
161 /** |
|
162 Specifies flags for the pool, as bit values from TShPoolCreateFlags or-ed together. |
|
163 |
|
164 @see TShPoolCreateFlags |
|
165 */ |
|
166 TUint iFlags; |
|
167 private: |
|
168 TInt iSpare1; // Reserved for future use |
|
169 TInt iSpare2; |
|
170 TInt iSpare3; |
|
171 TInt iSpare4; |
|
172 }; |
|
173 |
|
174 |
|
175 #endif // E32SHBUF_H |
|
176 |