There has been some confusion
in the past over which functions allocate their return values and
which functions return pointers to existing data. As of the Version
7 release, we have taken care to keep the treatment of return values
consistent. For example, all functions that return strings now return
“const char *” references to Alias data. We believe this approach
to be more general--it does not force the developer to perform extra
memory management if it is not necessary. If this returned string
is required for future reference, then it is up to the developer
to make a copy.
A Few Simple Rules for
Return Values
While the allocation
of return values may change and although there may be some exceptional
cases, here are some rules of thumb to remember.
- All methods that return strings return
a const char * reference that is not allocated.
- The downcasting methods in AlObject (as*Ptr)
do not allocate their return values. They simply act as a safe type
cast to the derived type.
- The AlObjects passed to an AlIterator
function are effectively not allocated. While they may still be
allocated internally, the developer need not, and should not, perform any
memory management on them - the applyIterator method handles that.
If the iterator needs to return a pointer to a wrapper object it
should copy it (that is, use the copyWrapper method).
- The destructive methods (methods whose
names end in “D”) do not perform any memory management. If they
succeed, they transform the passed in object in place. If they fail,
they do nothing to the passed in object.
- Otherwise, any other method that returns
a pointer to an object derived from AlObject allocates its return
value. If this return value is not later deallocated, it will cause
a memory leak.
It is important to remember
that return values will point to internal Alias objects that
may change. For example, the return of an Alias object’s name
may change due to an action performed in the interactive package.