4 Miscellaneous design notes

4.1 Destroying WObj:s

To keep Ion's code as simple as possible yet safe, there are restrictions when the WObj destroy_obj function that calls watches, the deinit routine and frees memory may be called directly. In all other cases the defer_destroy function should be used to defer the call of destroy_obj until Ioncore returns to its main event loop.

Calling the destroy_obj function directly is allowed in the following cases:

• In the deinit handler for another object. Usually managed objects are destroyed this way.
• The object was created during the current call to the function that wants to get rid of the object. This is the case, for example, when the function created a frame to manage some other object but for some reason failed to reparent the object to this frame.
• In a deferred action handler set with defer_action. Like deferred destroys, other deferred actions are called when Ioncore has returned to the main loop.
• You are absolute sure that C code outside your code has no references to the object.

If there are no serious side effects from deferring destroying the object or you're unsure whether it is safe to destroy the object immediately, use defer_destroy.

4.2 The types char* and const char* as function parameters and return values

The following rules should apply to using strings as return values and parameters to functions.

Type	Return value	Parameter
const char*	The string is owned by the called function and the caller is only quaranteed short-term read access to the string.	The called function may only read the string during its execution. For further reference a copy must be made.
char*	The string is the caller's responsibility and it must free it when no longer needed.	The called function may modify the string but the ''owner'' of the string is case-dependant.