Next: , Previous: Simple Operations, Up: Lists

3.1.2 Recoverable Operations

The functions in this section are similar to the ones in the previous section except with regard to error handling. Whereas the other ones cause an error message to be printed and the process to exit in the event of an overflow, these return to the caller, whose responsibility it is to take appropriate action. The functions in both sections are declared in lists.h, and should be preceded by a call to avm_initialize_lists.

— Function: list avm_recoverable_join (list left, list right)

This function is similar to avm_join, but will return a NULL pointer if memory that was needed can not be allocated. A NULL pointer would never be the result of a join under normal circumstances, so the overflow can be detected by the caller. Regardless of whether overflow occurs, the arguments are deallocated by this function and should not be referenced thereafter.

— Function: void avm_recoverable_enqueue (list *front, list *back, list operand, int *fault)

This version of the enqueue function will dispose of the operand if there isn't room to append another item and set *fault to a non-zero value. Other than that, it does the same as avm_enqueue.

— Function: counter avm_recoverable_length (list operand)

This function checks for arithmetic overflow when calculating the length of a list, and returns a zero value if overflow occurs. The caller can detect the error by noting that zero is not the length of any list other than NULL. This kind of overflow is impossible unless the host does not have long enough integers for its address space.

— Function: counter avm_recoverable_area (list operand, int *fault)

This function is similar to avm_area, except that it reacts differently to arithmetic overflow. The fault parameter should be the address of an integer known to the caller, which will be set to a non-zero value if overflow occurs. In that event, the value of zero will also be returned for the area. Note that it is possible for non-empty lists to have an area of zero, so this condition alone is not indicative of an error.

— Function: list avm_recoverable_natural (counter number)

This function returns the list representation of a native unsigned long integer, provided that there is enough memory, similarly to the avm_natural function. Unlike that function, this one will return a value of NULL rather than exiting the program in the event of a memory overflow. The overflow can be detected by the caller insofar as a NULL list does not represent any number other than zero.