TIP #298: Revise Shared Value Rules for Tcl_GetBignumAndClearObj


TIP:298
Title:Revise Shared Value Rules for Tcl_GetBignumAndClearObj
Version:$Revision: 1.6 $
Author:Don Porter <dgp at users dot sf dot net>
State:Final
Type:Project
Tcl-Version:8.5
Vote:Done
Created:Wednesday, 22 November 2006
Keywords:Tcl, Tcl_Obj

Abstract

This TIP proposes a revision to Tcl_GetBignumAndClearObj to make it easier to use.

Background

Tcl_GetBignumAndClearObj was added by TIP #237. Because mp_int values can be big, the interface is offered to avoid making a copy when the value already in the internal representation of an unshared Tcl_Obj will no longer be needed and can be moved instead of copied.

The basic intent was fine, but in practice, callers must go through these gymnastics to use it:

 if (Tcl_IsShared(objPtr)) {
     Tcl_GetBignumFromObj(interp, objPtr, &bigValue);
 } else {
     Tcl_GetBignumAndClearObj(interp, objPtr, &bigValue);
 }

It would make for a much more pleasant interface to move the test for a shared value into the routine itself.

Proposed Change

When passed a shared objPtr, Tcl_GetBignumAndClearObj will no longer panic, but will fall back to the copying behavior of Tcl_GetBignumFromObj. The use of the Tcl_GetBignumAndClearObj interface by a caller no longer means an assertion that objPtr is unshared, and no longer guarantees that objPtr will in fact be cleared, but merely indicates the caller will not be using the value anymore, and does not mind if it is cleared. That's all the caller should care about anyway.

Because of these changes in the implications and guarantees, the function is also renamed to Tcl_TakeBignumFromObj.

With these changes, the code above may be simplified to:

 Tcl_TakeBignumFromObj(interp, objPtr, &bigValue);

Compatibility

This is a incompatible change only with 8.5 alpha releases.

Reference Implementation

Available from [1].

Copyright

This document has been placed in the public domain.


Powered by Tcl[Index] [History] [HTML Format] [Source Format] [LaTeX Format] [Text Format] [XML Format] [*roff Format (experimental)] [RTF Format (experimental)]

TIP AutoGenerator - written by Donal K. Fellows