Introdução

Quando uma função Abandona (seja lançando o abandono diretamente ou através da execução de uma função que abandone) as variáveis automáticas que estão em seu escopo são destruídas. Este comportamento assemelha-se ao mecanismo padrão de exceções do C++ padrão porém com algumas diferenças:

1. Variáveis automáticas que sejam ponteiros são destruídas porém a memória alocada não será liberada;
2. O destrutor dos objetos não é executado.

Por esse motivo o Symbian implementou um mecanismo para que seja possível liberar os recursos alocados por ponteiros automáticos na ocorrência de Abandonos, este mecanismo é conhecido por Pilha de limpeza (Cleanup Stack).

Função que abandona

void AbandonaL()
{
    CClasse* p = new CMinhaClasse();
    p->FuncaoQueAbandonaL();
    delete p;
}

No código acima caso FuncaoQueAbandonaL() gere um abandono a instrução delete p nunca será chamada e como a memória alocada por p* não será liberada teremos um vazamento de memória.

A função da Pilha de limpeza é assegurar que os recursos alocados por ponteiros automáticos serão liberados na ocorrência de um abandono.

Utilização da pilha de limpeza

Para que a Pilha de limpeza libere os recursos alocados é preciso adicionar a pilha aqueles ponteiros que farão chamadas a métodos com possibilidade de abandono. Assim como qualquer pilha os elementos são adicionados e removidos baseados no princípio Último que entrou é o primeiro que sai (Last in, First Out). Uma vez que o código que lance um abandono seja executado com sucesso, caso não seja preciso executar outra operação com perigo de abandono o ponteiro deve ser removido da pilha.

A classe CleanupStack implementa diferentes métodos para adição/remoção de ponteiros a pilha de limpeza de modo que cada um implementa uma forma de limpeza diferente.

static IMPORT_C void PushL(TAny *aPtr);<br>
static IMPORT_C void PushL(CBase *aPtr);<br>
static IMPORT_C void PushL(TCleanupItem anItem);
static IMPORT_C void Pop();
static IMPORT_C void Pop(TInt aCount);
static IMPORT_C void PopAndDestroy();
static IMPORT_C void PopAndDestroy(TInt aCount);

PushL(TAny *aPtr)

Adiciona um ponteiro de qualquer objeto (exceto CBase) à pilha de limpeza. Limpeza: Libera a memória alocada sem fazer chamada ao destrutor da classe.

PushL(CBase* aPtr)

Adiciona um ponteiro de objetos do tipo CBase (que derivam direta ou indiretamente de CBase) à pilha de limpeza. Limpeza: Libera os recursos alocados e chama o destrutor da classe.

PushL(TCleanupItem anItem)

Adiciona um CleanupItem a pilha de limpeza. Limpeza: Será baseada na operação implementada pelo CleanupItem

Pop()

Remove da pilha o último elemento adicionado.

Pop(TInt aCount)

Remove um elemento específico da pilha.

PopAndDestroy()

Remove da pilha o último elemento adicionado e libera a memória alocada.

PopAndDestroy(TInt aCount)

Remove um elemento específico da pilha e libera a memória alocada.