15.1.1 Writing Functions

Writing new functions should be simple, and yet it isn’t. Special care should be taken with respect to setting up references to allocated resources, so that first they do get deallocated eventually, and second they don’t get deallocated too soon.

Temporaries are the resources created by functions that are accessible from outside the variables led references rings. Their deallocation needs to be arranged.

See Temporaries.

All resources made available by functions need to be properly shored up, not just the temporaries.

An example: a function may return an intrinsic string that it did not create itself. When the function was called, the string was referred by a list that the function received as a parameter, a list from which the function got the string from. After the function call, the list is destroyed or its content flushed. Likely, the original string is destroyed in the process. What the function should do is to make a temporary copy of the string and return that copy. Or, if instead an intrinsic string the returned value is a referable object, the function should increment the object reference count and arrange that a decrement will be done one the current expression evaluation completes.

Objects received as parameters are special. They can be outputted (returned, etc) without further shoring up.

The general guide should be that returned values and the overwritten variable held values should be made good until the expression evaluation completes. The latter will appear when functions modify their passed-by-reference arguments.

In a similar fashion, functions need to be extra careful when destroying resources. One destruction may trigger another, one that it is unintended and not permissible.

An example: a function flushes the content of its list first parameter. The function second parameter was a string in the first list, that gets destroyed too. Any attempt to use the string will likely end up very badly.

Unlike for aime coded functions, for which all parameters are properly shored up before call, and thus modifiable and destroyable without care, the parameters of C coded functions are not, with the responsibility of proper handling passed to the functions.

Thus destroying objects and removing references from allocated resources may need to be deferred until after the expression evaluation. Setting the function reference arguments needs special consideration, as it implies removing a variable held reference from an object.

The temporaries allocator constructs may be used to shore up the underreferenced resources and the referable object types (like those of the libaime libraries) have methods of adding and removing references.

See Temporaries Allocator Construct.

See x1f4_auto_text.