1 \section{Miscellaneous design notes}
3 \subsection{Destroying \type{WObj}:s}
5 To keep Ion's code as simple as possible yet safe, there are restrictions
7 \code{destroy_obj}\index{destroy-obj@\code{destroy_obj}}
8 function that calls watches, the deinit routine and frees memory may
9 be called directly. In all other cases the \code{mainloop_defer_destroy}%
10 \index{mainloop-defer-destroy@\code{mainloop_defer_destroy}}
11 function should be used to defer the call of \code{destroy_obj} until
12 Ioncore returns to its main event loop.
14 Calling the \code{destroy_obj} function directly is allowed in the
17 \item In the deinit handler for another object. Usually managed objects
18 are destroyed this way.
19 \item The object was created during the current call to the function
20 that wants to get rid of the object. This is the case, for example,
21 when the function created a frame to manage some other object but for
22 some reason failed to reparent the object to this frame.
23 \item In a deferred action handler set with \code{mainloop_defer_action}%
24 \index{mainloop-defer-action@\code{mainloop_defer_action}}.
25 Like deferred destroys, other deferred actions are called when
26 Ioncore has returned to the main loop.
27 \item You are absolute sure that C code outside your code has no
28 references to the object.
31 If there are no serious side effects from deferring destroying the
32 object or you're unsure whether it is safe to destroy the object
33 immediately, use \code{mainloop_defer_destroy}.
35 \subsection{The types \code{char*} and \code{const char*} as function
36 parameters and return values}
38 The following rules should apply to using strings as return values and
39 parameters to functions.
41 \begin{tabularx}{\linewidth}{lXX}
42 \tabhead{Type & Return value & Parameter}
43 \code{const char*} & The string is owned by the called function
44 and the caller is only quaranteed short-term read access to the
46 The called function may only read the string during its execution.
47 For further reference a copy must be made. \\
48 \code{char*} & The string is the caller's responsibility and it
49 \emph{must} free it when no longer needed. &
50 The called function may modify the string but the ``owner'' of
51 the string is case-dependant. \\