1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
|
\section{Miscellaneous design notes}
\subsection{Destroying \type{WObj}:s}
To keep Ion's code as simple as possible yet safe, there are restrictions
when the \type{WObj}
\code{destroy_obj}\index{destroy-obj@\code{destroy_obj}}
function that calls watches, the deinit routine and frees memory may
be called directly. In all other cases the \code{mainloop_defer_destroy}%
\index{mainloop-defer-destroy@\code{mainloop_defer_destroy}}
function should be used to defer the call of \code{destroy_obj} until
Ioncore returns to its main event loop.
Calling the \code{destroy_obj} function directly is allowed in the
following cases:
\begin{itemize}
\item In the deinit handler for another object. Usually managed objects
are destroyed this way.
\item 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.
\item In a deferred action handler set with \code{mainloop_defer_action}%
\index{mainloop-defer-action@\code{mainloop_defer_action}}.
Like deferred destroys, other deferred actions are called when
Ioncore has returned to the main loop.
\item You are absolute sure that C code outside your code has no
references to the object.
\end{itemize}
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 \code{mainloop_defer_destroy}.
\subsection{The types \code{char*} and \code{const char*} as function
parameters and return values}
The following rules should apply to using strings as return values and
parameters to functions.
\begin{tabularx}{\linewidth}{lXX}
\tabhead{Type & Return value & Parameter}
\code{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. \\
\code{char*} & The string is the caller's responsibility and it
\emph{must} free it when no longer needed. &
The called function may modify the string but the ``owner'' of
the string is case-dependant. \\
\end{tabularx}
|
