3.7.7 Freeing Discarded Symbols

During error recovery (see section Error Recovery), symbols already pushed on the stack and tokens coming from the rest of the file are discarded until the parser falls on its feet. If the parser runs out of memory, or if it returns via YYABORT or YYACCEPT, all the symbols on the stack must be discarded. Even if the parser succeeds, it must discard the start symbol.

When discarded symbols convey heap based information, this memory is lost. While this behavior can be tolerable for batch parsers, such as in traditional compilers, it is unacceptable for programs like shells or protocol implementations that may parse and execute indefinitely.

The %destructor directive defines code that is called when a symbol is automatically discarded.

Directive: %destructor { code } symbols

Invoke the braced code whenever the parser discards one of the symbols. Within code, $$ designates the semantic value associated with the discarded symbol. The additional parser parameters are also available (see section The Parser Function yyparse).

For instance:

%union
{
  char *string;
}
%token <string> STRING
%type  <string> string
%destructor { free ($$); } STRING string

guarantees that when a STRING or a string is discarded, its associated memory will be freed.

Discarded symbols are the following:

• stacked symbols popped during the first phase of error recovery,
• incoming terminals during the second phase of error recovery,
• the current look-ahead and the entire stack (except the current right-hand side symbols) when the parser returns immediately, and
• the start symbol, when the parser succeeds.

The parser can return immediately because of an explicit call to YYABORT or YYACCEPT, or failed error recovery, or memory exhaustion.

Right-hand size symbols of a rule that explicitly triggers a syntax error via YYERROR are not discarded automatically. As a rule of thumb, destructors are invoked only when user actions cannot manage the memory.