Author:         Jan Nijtmans <[email protected]>
State:          Draft
Type:           Project
Tcl-Version:    9.1
Tcl-Branch:     attemptcreatehashentry

---

Abstract

This TIP proposes a new function Tcl_AttemptCreateHashEntry(). It does almost the same as Tcl_CreateHashEntry(), only in case of failing memory allocation it returns NULL in stead of panicing.

In addition, the last isNew argument of Tcl_CreateHashEntry()/ Tcl_AttemptCreateHashEntry() now accepts NULL as possible value, which can be used if the caller is not interested in knowing whether the function created a new entry or not.

Rationale

The new function allows to handle memory exhaustion better than the old function does. Some existing code (e.g. in tclClockFmt.c) already checks the hPtr for being non-zero, something that can never happen with Tcl_CreateHashEntry().

The main place this new function will be used in handling dictionaries, the same way as lists are already handled now: When they become huge, causing memory exhaustion, it's better to clear its contents and give an error-message than panicing. This improved dict handling is not done yet in this TIP implementation.

The reason for allowing newPtr to be NULL, is saving the allocation of a dummy variable. This TIP implementation contains many examples.

Specification

Declare and implement a new function:

• Tcl_HashEntry *Tcl_AttemptCreateHashEntry(Tcl_HashTable *tablePtr, const char *key, int *newPtr);

The newPtr argument is allowed to be NULL. The newPtr argument from Tcl_CreateHashEntry() is now allowed to be NULL as well.

Implementation

See the attemptcreatehashentry branch.

Copyright

This document has been placed in the public domain.