|
1 // Copyright (c) 1995-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". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // e32\euser\cbase\ub_cln.cpp |
|
15 // |
|
16 // |
|
17 |
|
18 #include "ub_std.h" |
|
19 #include "us_data.h" |
|
20 |
|
21 const TInt KCleanupGranularity=4; |
|
22 const TInt KCleanupInitialSlots=8; |
|
23 |
|
24 LOCAL_C void doDelete(CBase *aPtr) |
|
25 // |
|
26 // Delete the CBase pointer |
|
27 // |
|
28 { |
|
29 |
|
30 delete aPtr; |
|
31 } |
|
32 |
|
33 LOCAL_C CCleanup &cleanup() |
|
34 // |
|
35 // Return the CTrapHandler's cleanup list. |
|
36 // |
|
37 { |
|
38 |
|
39 TCleanupTrapHandler *pH=(TCleanupTrapHandler *)GetTrapHandler(); |
|
40 __ASSERT_ALWAYS(pH!=NULL,Panic(EClnNoTrapHandlerInstalled)); |
|
41 return(pH->Cleanup()); |
|
42 } |
|
43 |
|
44 |
|
45 |
|
46 |
|
47 TCleanupTrapHandler::TCleanupTrapHandler() |
|
48 : iCleanup(NULL) |
|
49 /** |
|
50 Default constructor. |
|
51 */ |
|
52 {} |
|
53 |
|
54 |
|
55 |
|
56 |
|
57 void TCleanupTrapHandler::Trap() |
|
58 /** |
|
59 Deals with the invocation of a call to TRAP. |
|
60 */ |
|
61 { |
|
62 |
|
63 iCleanup->NextLevel(); |
|
64 } |
|
65 |
|
66 |
|
67 |
|
68 |
|
69 void TCleanupTrapHandler::UnTrap() |
|
70 /** |
|
71 Deals with a function exiting a TRAP without leaving. |
|
72 */ |
|
73 { |
|
74 |
|
75 iCleanup->PreviousLevel(); |
|
76 } |
|
77 |
|
78 |
|
79 |
|
80 |
|
81 void TCleanupTrapHandler::Leave(TInt /*aValue*/) |
|
82 /** |
|
83 Deals with a function within a TRAP leaving. |
|
84 |
|
85 @param aValue The leave value. |
|
86 */ |
|
87 { |
|
88 |
|
89 iCleanup->PopAndDestroyAll(); |
|
90 } |
|
91 |
|
92 |
|
93 |
|
94 |
|
95 class TCleanupStackItem |
|
96 { |
|
97 public: |
|
98 void Set(const TCleanupItem &aItem); |
|
99 inline void Cleanup(); |
|
100 inline TBool IsLevelMarker() const; |
|
101 inline void MarkLevel(); |
|
102 inline void PushLevel(); |
|
103 inline TInt PopLevel(); |
|
104 inline TBool Check(TAny* aExpectedItem) const; |
|
105 private: |
|
106 TCleanupOperation iOperation; |
|
107 union |
|
108 { |
|
109 TAny *iPtr; |
|
110 TInt iLevelCount; // may stack >1 level on this entry |
|
111 }; |
|
112 }; |
|
113 inline void TCleanupStackItem::MarkLevel() |
|
114 { iOperation=NULL; iLevelCount=1; } |
|
115 inline TBool TCleanupStackItem::IsLevelMarker() const |
|
116 { return (iOperation==NULL); } |
|
117 inline void TCleanupStackItem::Cleanup() |
|
118 { (*iOperation)(iPtr); } |
|
119 inline void TCleanupStackItem::PushLevel() |
|
120 { ++iLevelCount; } |
|
121 inline TInt TCleanupStackItem::PopLevel() |
|
122 { return (--iLevelCount); } |
|
123 inline TBool TCleanupStackItem::Check(TAny* aExpectedItem) const |
|
124 { return (iOperation && iPtr==aExpectedItem); } |
|
125 |
|
126 void TCleanupStackItem::Set(const TCleanupItem &anItem) |
|
127 // |
|
128 // Initialise an entry as a cleanup item. |
|
129 // |
|
130 { |
|
131 |
|
132 __ASSERT_ALWAYS(anItem.iOperation!=NULL,Panic(EClnNoCleanupOperation)); |
|
133 iOperation=anItem.iOperation; |
|
134 iPtr=anItem.iPtr; |
|
135 } |
|
136 |
|
137 |
|
138 |
|
139 |
|
140 EXPORT_C CCleanup *CCleanup::New() |
|
141 /** |
|
142 Creates a new cleanup stack object. |
|
143 |
|
144 The cleanup stack itself is allocated with enough space initially to hold |
|
145 a number of stack items. |
|
146 |
|
147 @return A pointer to the new cleanup stack object. This is Null if there is |
|
148 insufficient memory. |
|
149 */ |
|
150 { |
|
151 |
|
152 CCleanup *pC=new CCleanup; |
|
153 if (pC!=NULL) |
|
154 { |
|
155 TCleanupStackItem *base=(TCleanupStackItem *)User::Alloc(KCleanupInitialSlots*sizeof(TCleanupStackItem)); |
|
156 if (base!=NULL) |
|
157 { |
|
158 pC->iBase=base; |
|
159 pC->iNext=base; |
|
160 pC->iTop=base+KCleanupInitialSlots; |
|
161 } |
|
162 else |
|
163 { |
|
164 delete pC; |
|
165 pC=NULL; |
|
166 } |
|
167 } |
|
168 return(pC); |
|
169 } |
|
170 |
|
171 |
|
172 |
|
173 |
|
174 EXPORT_C CCleanup *CCleanup::NewL() |
|
175 /** |
|
176 Creates a new cleanup stack object, and leaves if there is insufficient memory |
|
177 to create it. |
|
178 |
|
179 The cleanup stack itself is allocated with enough space initially to hold |
|
180 a number of stack items. |
|
181 |
|
182 @return A pointer to the new cleanup stack object. This is Null if there is |
|
183 nsufficient memory. |
|
184 */ |
|
185 { |
|
186 |
|
187 CCleanup *pC=New(); |
|
188 User::LeaveIfNull(pC); |
|
189 return(pC); |
|
190 } |
|
191 |
|
192 |
|
193 |
|
194 |
|
195 EXPORT_C CCleanup::CCleanup() |
|
196 /** |
|
197 Default constructor. |
|
198 */ |
|
199 { |
|
200 |
|
201 // iBase=NULL; |
|
202 // iTop=NULL; |
|
203 // iNext=NULL; |
|
204 } |
|
205 |
|
206 |
|
207 |
|
208 |
|
209 EXPORT_C CCleanup::~CCleanup() |
|
210 /** |
|
211 Destructor. |
|
212 |
|
213 Pops and destroys all items from the cleanup stack and then destroys |
|
214 the cleanup stack itself. |
|
215 */ |
|
216 { |
|
217 |
|
218 while (iNext>iBase) |
|
219 PopAndDestroyAll(); |
|
220 User::Free(iBase); |
|
221 } |
|
222 |
|
223 |
|
224 |
|
225 |
|
226 EXPORT_C void CCleanup::NextLevel() |
|
227 /** |
|
228 Goes to the next cleanup level. |
|
229 */ |
|
230 { |
|
231 |
|
232 if (iNext>iBase && (iNext-1)->IsLevelMarker()) |
|
233 (iNext-1)->PushLevel(); |
|
234 else |
|
235 { |
|
236 iNext->MarkLevel(); |
|
237 ++iNext; |
|
238 } |
|
239 } |
|
240 |
|
241 |
|
242 |
|
243 |
|
244 EXPORT_C void CCleanup::PreviousLevel() |
|
245 /** |
|
246 Goes to the previous cleanup level. |
|
247 |
|
248 @panic E32USER-CBase 71 If the previous stack item does not represent a cleanup |
|
249 level. |
|
250 */ |
|
251 { |
|
252 |
|
253 TCleanupStackItem *item=iNext; |
|
254 --item; |
|
255 // current level must be empty |
|
256 __ASSERT_ALWAYS(item->IsLevelMarker(), Panic(EClnLevelNotEmpty)); |
|
257 if (item->PopLevel()) |
|
258 ++item; |
|
259 iNext=item; |
|
260 } |
|
261 |
|
262 |
|
263 |
|
264 |
|
265 EXPORT_C void CCleanup::PushL(TAny *aPtr) |
|
266 /** |
|
267 Pushes a cleanup item onto the cleanup stack. |
|
268 |
|
269 The cleanup item represents an operation that frees the specified heap cell. |
|
270 |
|
271 @param aPtr A pointer to a heap cell that will be freed by |
|
272 the cleanup operation. |
|
273 */ |
|
274 { |
|
275 |
|
276 PushL(TCleanupItem(User::Free,aPtr)); |
|
277 } |
|
278 |
|
279 |
|
280 |
|
281 |
|
282 EXPORT_C void CCleanup::PushL(CBase *anObject) |
|
283 /** |
|
284 Pushes a cleanup item onto the cleanup stack. |
|
285 |
|
286 The cleanup item represents an operation that deletes the specified CBase |
|
287 derived object. |
|
288 |
|
289 @param anObject A pointer to CBase derived object that will be deleted by |
|
290 the cleanup operation. |
|
291 */ |
|
292 { |
|
293 |
|
294 PushL(TCleanupItem(TCleanupOperation(doDelete),anObject)); |
|
295 } |
|
296 |
|
297 |
|
298 |
|
299 |
|
300 EXPORT_C void CCleanup::PushL(TCleanupItem anItem) |
|
301 /** |
|
302 Pushes a cleanup item onto the cleanup stack. |
|
303 |
|
304 The cleanup item represents a call back operation that performs the required |
|
305 cleanup. |
|
306 |
|
307 @param anItem Encapsulates a cleanup operation and an object on which the |
|
308 cleanup operation is to be performed. |
|
309 |
|
310 @see CleanupClosePushL |
|
311 @see CleanupReleasePushL |
|
312 @see CleanupDeletePushL |
|
313 */ |
|
314 { |
|
315 |
|
316 TCleanupStackItem *item=iNext; |
|
317 __ASSERT_ALWAYS(item>iBase,Panic(EClnPushAtLevelZero)); |
|
318 __ASSERT_ALWAYS(item<iTop,Panic(EClnNoFreeSlotItem)); |
|
319 item->Set(anItem); |
|
320 iNext=++item; |
|
321 // |
|
322 // We always try and make sure that there are two free slots in the cleanup array. |
|
323 // one for a level marker and one for an item to follow it |
|
324 // If this fails its o.k. as we have already added the entry to the list, so |
|
325 // it will be cleaned up o.k. |
|
326 // |
|
327 if (item+1>=iTop) |
|
328 { |
|
329 TInt size=(TUint8 *)(iTop+KCleanupGranularity)-(TUint8 *)iBase; |
|
330 TCleanupStackItem *base=(TCleanupStackItem *)User::ReAllocL(iBase,size); |
|
331 iNext=PtrAdd(base,(TUint8 *)item-(TUint8 *)iBase); |
|
332 iBase=base; |
|
333 iTop=PtrAdd(base,size); |
|
334 } |
|
335 } |
|
336 |
|
337 |
|
338 |
|
339 |
|
340 EXPORT_C void CCleanup::DoPop(TInt aCount,TBool aDestroy) |
|
341 /** |
|
342 Provides an implementation for Pop() and PopAndDestroy(). |
|
343 |
|
344 @param aCount The number of cleanup items to be popped from |
|
345 the cleanup stack. |
|
346 @param aDestroy ETrue, if cleanup is to be performed; EFalse, otherwise. |
|
347 */ |
|
348 { |
|
349 |
|
350 __ASSERT_ALWAYS(aCount>=0,Panic(EClnPopCountNegative)); |
|
351 __ASSERT_ALWAYS((iNext-aCount)>=iBase,Panic(EClnPopUnderflow)); |
|
352 while (aCount--) |
|
353 { |
|
354 --iNext; |
|
355 __ASSERT_ALWAYS(!iNext->IsLevelMarker(),Panic(EClnPopAcrossLevels)); |
|
356 if (aDestroy) |
|
357 { |
|
358 TInt offset = iNext - iBase; |
|
359 iNext->Cleanup(); |
|
360 // Check that there are no extra items on the cleanup stack |
|
361 // (if there are, we will not be deleting the right aCount items) |
|
362 __ASSERT_ALWAYS((iNext - iBase) == offset,Panic(EClnStackModified)); |
|
363 } |
|
364 } |
|
365 } |
|
366 |
|
367 |
|
368 |
|
369 |
|
370 EXPORT_C void CCleanup::DoPopAll(TBool aDestroy) |
|
371 /** |
|
372 Provides an implementation for PopAll() and PopAndDestroyAll(). |
|
373 |
|
374 @param aDestroy ETrue, if cleanup is to be performed; EFalse, otherwise. |
|
375 */ |
|
376 { |
|
377 |
|
378 __ASSERT_ALWAYS(iNext>iBase,Panic(EClnLevelUnderflow)); |
|
379 while (!(--iNext)->IsLevelMarker()) |
|
380 { |
|
381 if (aDestroy) |
|
382 iNext->Cleanup(); |
|
383 } |
|
384 if (iNext->PopLevel()) |
|
385 ++iNext; // still marks a level |
|
386 } |
|
387 |
|
388 |
|
389 |
|
390 |
|
391 EXPORT_C void CCleanup::Pop() |
|
392 /** |
|
393 Pops a single cleanup item from the cleanup stack. |
|
394 |
|
395 @panic E32USER-CBase 64 If there are no items on the cleanup stack. |
|
396 @panic E32USER-CBase 63 If a cleanup level is crossed. |
|
397 */ |
|
398 { |
|
399 |
|
400 DoPop(1,EFalse); |
|
401 } |
|
402 |
|
403 |
|
404 |
|
405 |
|
406 EXPORT_C void CCleanup::Pop(TInt aCount) |
|
407 /** |
|
408 Pops the specified number of cleanup items from the cleanup stack. |
|
409 |
|
410 @param aCount The number of cleanup items to be popped from the cleanup stack. |
|
411 |
|
412 @panic E32USER-CBase 70 If the specified number of cleanup items is negative. |
|
413 @panic E32USER-CBase 64 If the specifed number of items is greater than the |
|
414 number of items on the cleanup stack. |
|
415 @panic E32USER-CBase 63 If the specified number of items is such that it causes |
|
416 a cleanup level to be crossed. |
|
417 */ |
|
418 { |
|
419 |
|
420 DoPop(aCount,EFalse); |
|
421 } |
|
422 |
|
423 |
|
424 |
|
425 |
|
426 EXPORT_C void CCleanup::PopAll() |
|
427 /** |
|
428 Pops all cleanup items at the current level, and then decrements the level. |
|
429 */ |
|
430 { |
|
431 |
|
432 DoPopAll(EFalse); |
|
433 } |
|
434 |
|
435 |
|
436 |
|
437 |
|
438 EXPORT_C void CCleanup::PopAndDestroy() |
|
439 /** |
|
440 Pops a single cleanup item from the cleanup stack, and invokes its cleanup |
|
441 operation. |
|
442 |
|
443 @panic E32USER-CBase 64 If there are no items on the cleanup stack. |
|
444 @panic E32USER-CBase 63 If a cleanup level is crossed. |
|
445 */ |
|
446 { |
|
447 |
|
448 DoPop(1,ETrue); |
|
449 } |
|
450 |
|
451 |
|
452 |
|
453 |
|
454 EXPORT_C void CCleanup::PopAndDestroy(TInt aCount) |
|
455 /** |
|
456 Pops the specified number of cleanup items from the cleanup stack, and invokes |
|
457 their cleanup operations. |
|
458 |
|
459 @param aCount The number of cleanup items to be popped from the cleanup stack. |
|
460 |
|
461 @panic E32USER-CBase 70 If the specified number of cleanup items is negative. |
|
462 @panic E32USER-CBase 64 If the specifed number of items is greater than the |
|
463 number of items on the cleanup stack. |
|
464 @panic E32USER-CBase 63 If the specified number of items is such that it causes |
|
465 a cleanup level to be crossed. |
|
466 */ |
|
467 { |
|
468 |
|
469 DoPop(aCount,ETrue); |
|
470 } |
|
471 |
|
472 |
|
473 |
|
474 |
|
475 EXPORT_C void CCleanup::PopAndDestroyAll() |
|
476 /** |
|
477 Pops all cleanup items at the current level, invokes their cleanup operations |
|
478 and then decrements the level. |
|
479 */ |
|
480 { |
|
481 |
|
482 DoPopAll(ETrue); |
|
483 } |
|
484 |
|
485 |
|
486 |
|
487 |
|
488 EXPORT_C void CCleanup::Check(TAny* aExpectedItem) |
|
489 /** |
|
490 Checks that the cleanup item at the top of the cleanup stack |
|
491 represents a cleanup operation for the specified object. |
|
492 |
|
493 @param aExpectedItem The object which is the subject of the test. |
|
494 */ |
|
495 { |
|
496 |
|
497 TCleanupStackItem* last=iNext-1; |
|
498 __ASSERT_ALWAYS(last>=iBase && last->Check(aExpectedItem), Panic(EClnCheckFailed)); |
|
499 } |
|
500 |
|
501 |
|
502 |
|
503 |
|
504 EXPORT_C CTrapCleanup *CTrapCleanup::New() |
|
505 /** |
|
506 Allocates and constructs a cleanup stack. |
|
507 |
|
508 If successfully constructed, this cleanup stack becomes |
|
509 the current cleanup stack. |
|
510 |
|
511 @return A pointer to the new cleanup stack. This pointer is NULL, if allocation |
|
512 fails. |
|
513 */ |
|
514 { |
|
515 |
|
516 CTrapCleanup *pT=new CTrapCleanup; |
|
517 if (pT!=NULL) |
|
518 { |
|
519 CCleanup *pC=CCleanup::New(); |
|
520 if (pC!=NULL) |
|
521 { |
|
522 pT->iHandler.iCleanup=pC; |
|
523 pT->iOldHandler=User::SetTrapHandler(&pT->iHandler); |
|
524 } |
|
525 else |
|
526 { |
|
527 delete pT; |
|
528 pT=NULL; |
|
529 } |
|
530 } |
|
531 return(pT); |
|
532 } |
|
533 |
|
534 |
|
535 |
|
536 |
|
537 EXPORT_C CTrapCleanup::CTrapCleanup() |
|
538 /** |
|
539 Default constructor. |
|
540 */ |
|
541 // : iHandler() |
|
542 { |
|
543 } |
|
544 |
|
545 |
|
546 |
|
547 |
|
548 EXPORT_C CTrapCleanup::~CTrapCleanup() |
|
549 /** |
|
550 Destructor. |
|
551 |
|
552 Frees resources owned by the object, prior to its destruction. This cleanup |
|
553 stack ceases to be the current cleanup stack. |
|
554 |
|
555 If there is a stack of cleanup stacks, then the next cleanup stack becomes |
|
556 the current cleanup stack. |
|
557 */ |
|
558 { |
|
559 |
|
560 if (iHandler.iCleanup!=NULL) |
|
561 { |
|
562 User::SetTrapHandler(iOldHandler); |
|
563 delete iHandler.iCleanup; |
|
564 } |
|
565 } |
|
566 |
|
567 |
|
568 |
|
569 |
|
570 EXPORT_C void CleanupStack::PushL(TAny *aPtr) |
|
571 /** |
|
572 Pushes a pointer to an object onto the cleanup stack. |
|
573 |
|
574 If a leave occurs while an object is on the stack, it is cleaned |
|
575 up automatically. Untyped objects are cleaned up with User::Free() |
|
576 (a rather limited form of cleanup, not even the C++ destructor is called). |
|
577 |
|
578 Typically, when an object has been fully constructed and it can be guaranteed |
|
579 that a pointer to this new object is stored in some other object before a leave |
|
580 occurs, issue CleanupStack::Pop() to pop it back off the stack. |
|
581 |
|
582 If no cleanup stack has been allocated, a panic occurs. |
|
583 |
|
584 It is guaranteed that the object is pushed onto the cleanup stack. However, |
|
585 this function may leave if a stack frame for the next PushL() cannot be |
|
586 allocated. In this case, the cleanup stack will be cleaned up as normal, and |
|
587 no extra programmer intervention is needed. |
|
588 |
|
589 @param aPtr Pointer to any object. If cleanup is necessary, the object will be |
|
590 freed by User::Free(), which does not invoke any destructor: it |
|
591 simply frees its memory |
|
592 |
|
593 @panic E32USER-CBase 66 if a call to this function is made when no prior |
|
594 call to TRAP has been made. |
|
595 */ |
|
596 { |
|
597 |
|
598 cleanup().PushL(aPtr); |
|
599 } |
|
600 |
|
601 |
|
602 |
|
603 |
|
604 EXPORT_C void CleanupStack::PushL(CBase *aPtr) |
|
605 /** |
|
606 Pushes a pointer to an object onto the cleanup stack. |
|
607 |
|
608 If a leave occurs while an object is on the stack, it is cleaned |
|
609 up automatically. CBase derived objects are cleaned up with delete. |
|
610 |
|
611 Typically, when an object has been fully constructed and it can be guaranteed |
|
612 that a pointer to this new object is stored in some other object before a leave |
|
613 occurs, issue CleanupStack::Pop() to pop it back off the stack. |
|
614 |
|
615 If no cleanup stack has been allocated, a panic occurs. |
|
616 |
|
617 It is guaranteed that the object is pushed onto the cleanup stack. However, |
|
618 this function may leave if a stack frame for the next PushL() cannot be |
|
619 allocated. In this case, the cleanup stack will be cleaned up as normal, |
|
620 and no extra programmer intervention is needed. |
|
621 |
|
622 @param aPtr Pointer to a CBase-derived object. If cleanup is necessary, the |
|
623 object will be freed by delete, thus invoking its destructor, |
|
624 and freeing its memory. |
|
625 |
|
626 @panic E32USER-CBase 66 if a call to this function is made when no prior |
|
627 call to TRAP has been made. |
|
628 */ |
|
629 { |
|
630 |
|
631 cleanup().PushL(aPtr); |
|
632 } |
|
633 |
|
634 |
|
635 |
|
636 |
|
637 EXPORT_C void CleanupStack::PushL(TCleanupItem anItem) |
|
638 /** |
|
639 Pushes a cleanup item onto the cleanup stack. |
|
640 |
|
641 If a leave occurs while a cleanup item is on the stack, the cleanup operation |
|
642 defined in the construction of the TCleanupItem, is invoked. |
|
643 |
|
644 Typically, when an object has been fully constructed and it can be guaranteed |
|
645 that a pointer to this new object is stored in some other object before a leave |
|
646 occurs, issue CleanupStack::Pop() to pop it back off the stack. |
|
647 |
|
648 If no cleanup stack has been allocated, a panic occurs. |
|
649 |
|
650 It is guaranteed that the object is pushed onto the cleanup stack. However, |
|
651 this function may leave if a stack frame for the next PushL() cannot be |
|
652 allocated. In this case, the cleanup stack will be cleaned up as normal, |
|
653 and no extra programmer intervention is needed. |
|
654 |
|
655 @param anItem A cleanup item. If cleanup is necessary, the cleanup operation |
|
656 defined in the construction of anItem is called. |
|
657 |
|
658 @panic E32USER-CBase 66 if a call to this function is made when no prior |
|
659 call to TRAP has been made. |
|
660 */ |
|
661 { |
|
662 |
|
663 cleanup().PushL(anItem); |
|
664 } |
|
665 |
|
666 |
|
667 |
|
668 |
|
669 EXPORT_C void CleanupStack::Pop() |
|
670 /** |
|
671 Pops an object previously pushed onto the cleanup stack |
|
672 by CleanupStack::PushL(). |
|
673 |
|
674 After an object has been successfully constructed and stored within |
|
675 another object, it cannot be orphaned and, therefore, the object |
|
676 (i.e. a pointer or a cleanup item) can be popped from the cleanup stack. |
|
677 |
|
678 If no cleanup stack has been allocated, or there is nothing on the stack, |
|
679 a panic is raised. |
|
680 */ |
|
681 { |
|
682 |
|
683 cleanup().Pop(); |
|
684 } |
|
685 |
|
686 |
|
687 |
|
688 |
|
689 EXPORT_C void CleanupStack::Pop(TInt aCount) |
|
690 /** |
|
691 Pops a specified number of objects previously pushed onto the |
|
692 cleanup stack by CleanupStack::PushL(). |
|
693 |
|
694 After an object has been successfully constructed and stored within another |
|
695 object, it cannot be orphaned and, therefore, the object(s), that is, pointers |
|
696 and cleanup items can be popped from the cleanup stack. |
|
697 |
|
698 If no cleanup stack has been allocated, or there is nothing on the stack, |
|
699 a panic is raised. |
|
700 |
|
701 @param aCount The number of objects to be popped off the cleanup stack. |
|
702 */ |
|
703 { |
|
704 |
|
705 cleanup().Pop(aCount); |
|
706 } |
|
707 |
|
708 |
|
709 |
|
710 |
|
711 EXPORT_C void CleanupStack::PopAndDestroy() |
|
712 /** |
|
713 Pops and cleans up an item pushed onto the stack. |
|
714 |
|
715 If the item on the stack is a CBase* pointer, the pointer is removed from |
|
716 the stack and the object is destroyed with delete. |
|
717 |
|
718 If the item on the stack is a TAny* pointer, the pointer is removed from |
|
719 the stack and the memory occupied by the object is freed with User::Free(). |
|
720 |
|
721 If the item on the stack is a cleanup item, i.e. an object of |
|
722 type TCleanupItem, the item is removed from the stack and the cleanup |
|
723 operation defined during construction of the TCleanupItem object is invoked. |
|
724 |
|
725 If no cleanup stack has been allocated, or there is nothing on the stack, |
|
726 a panic occurs. |
|
727 */ |
|
728 { |
|
729 |
|
730 cleanup().PopAndDestroy(); |
|
731 } |
|
732 |
|
733 |
|
734 |
|
735 |
|
736 EXPORT_C void CleanupStack::PopAndDestroy(TInt aCount) |
|
737 /** |
|
738 Pops and cleans up the specified number of items pushed onto the stack. |
|
739 |
|
740 If an item on the stack is a CBase* pointer, the pointer is removed from |
|
741 the stack and the object is destroyed with delete. |
|
742 |
|
743 If an item on the stack is a TAny* pointer, the pointer is removed from the |
|
744 stack and the memory occupied by the object is freed with User::Free(). |
|
745 |
|
746 If an item on the stack is a cleanup item, i.e. an object of type TCleanupItem, |
|
747 the item is removed from the stack and the cleanup operation defined during |
|
748 construction of the TCleanupItem object is invoked. |
|
749 |
|
750 If no cleanup stack has been allocated, or there is nothing on the stack, |
|
751 a panic occurs. |
|
752 |
|
753 @param aCount The number of objects to be popped off the cleanup stack and |
|
754 destroyed. |
|
755 */ |
|
756 { |
|
757 |
|
758 cleanup().PopAndDestroy(aCount); |
|
759 } |
|
760 |
|
761 |
|
762 |
|
763 |
|
764 EXPORT_C void CleanupStack::Check(TAny* aExpectedItem) |
|
765 /** |
|
766 Checks that the specified object is at the top of the cleanup stack. |
|
767 |
|
768 If the specified item is not at the top of the cleanup stack, then the function |
|
769 raises an E32USER-CBase 90 panic. |
|
770 |
|
771 The function is part of Symbian OS in both debug and release builds, and is |
|
772 an aid to debugging. |
|
773 |
|
774 @param aExpectedItem A pointer to the item expected to be at the top of the |
|
775 cleanup stack. |
|
776 */ |
|
777 { |
|
778 |
|
779 cleanup().Check(aExpectedItem); |
|
780 } |