5 Miscellaneous design notes

5.1 Destroying WObj's

To keep Notion'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 mainloop_defer_destroy function should be used to defer the call of destroy_obj until Notioncore 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 mainloop_defer_action. Like deferred destroys, other deferred actions are called when Notioncore 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 mainloop_defer_destroy.

5.2 Method signatures

5.2.1 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.

5.2.2 Use of pointers

When a method has a pointer as a parameter, and there may be confusion over whether parameter may be NULL, it is encouraged to add http://www.splint.org-style annotations such as /*@notnull@*/ and /*@null@*/.

5.3 Encoding

Unless otherwise specified, character strings are encoded in the current locale's encoding. Convenience booleans ioncore_g.enc_sb, ioncore_g.use_mb and ioncore_g.enc_utf8 may be used to determine whether the current locale's encoding is 8-bit, whether to use multi-byte routines and whether the multi-byte encoding is UTF-8.