1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
3 <!--Converted with LaTeX2HTML 2002-2-1 (1.71)
4 original version by: Nikos Drakos, CBLU, University of Leeds
5 * revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
6 * with significant contributions from:
7 Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
10 <TITLE>4 Miscellaneous design notes</TITLE>
11 <META NAME="description" CONTENT="4 Miscellaneous design notes">
12 <META NAME="keywords" CONTENT="ionnotes">
13 <META NAME="resource-type" CONTENT="document">
14 <META NAME="distribution" CONTENT="global">
16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
17 <META NAME="Generator" CONTENT="LaTeX2HTML v2002-2-1">
18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
20 <LINK REL="STYLESHEET" HREF="ionnotes.css">
22 <LINK REL="next" HREF="node6.html">
23 <LINK REL="previous" HREF="node4.html">
24 <LINK REL="up" HREF="ionnotes.html">
25 <LINK REL="next" HREF="node6.html">
30 <DIV CLASS="navigation"><!--Navigation Panel-->
33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
47 <B> Next:</B> <A NAME="tex2html134"
48 HREF="node6.html">5 C coding style</A>
49 <B> Up:</B> <A NAME="tex2html128"
50 HREF="ionnotes.html">Ion: Notes for the</A>
51 <B> Previous:</B> <A NAME="tex2html122"
52 HREF="node4.html">3 The Lua interface</A>
53 <B> <A NAME="tex2html130"
54 HREF="node1.html">Contents</A></B>
55 <B> <A NAME="tex2html132"
56 HREF="node8.html">Index</A></B>
59 <!--End of Navigation Panel-->
60 <!--Table of Child-Links-->
61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
63 <UL CLASS="ChildLinks">
64 <LI><A NAME="tex2html135"
65 HREF="node5.html#SECTION00051000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Destroying WObj:s</A>
66 <LI><A NAME="tex2html136"
67 HREF="node5.html#SECTION00052000000000000000"><SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> The types <TT>char*</TT> and <TT>const char*</TT> as function
68 parameters and return values</A>
70 <!--End of Table of Child-Links-->
73 <H1><A NAME="SECTION00050000000000000000">
74 <SPAN CLASS="arabic">4</SPAN> Miscellaneous design notes</A>
79 <H2><A NAME="SECTION00051000000000000000">
80 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Destroying WObj:s</A>
84 To keep Ion's code as simple as possible yet safe, there are restrictions
86 <TT>destroy_obj</TT><A NAME="617"></A>
87 function that calls watches, the deinit routine and frees memory may
88 be called directly. In all other cases the <TT>mainloop_defer_destroy</TT><A NAME="618"></A>
89 function should be used to defer the call of <TT>destroy_obj</TT> until
90 Ioncore returns to its main event loop.
93 Calling the <TT>destroy_obj</TT> function directly is allowed in the
97 <LI>In the deinit handler for another object. Usually managed objects
98 are destroyed this way.
100 <LI>The object was created during the current call to the function
101 that wants to get rid of the object. This is the case, for example,
102 when the function created a frame to manage some other object but for
103 some reason failed to reparent the object to this frame.
105 <LI>In a deferred action handler set with <TT>mainloop_defer_action</TT><A NAME="619"></A>.
106 Like deferred destroys, other deferred actions are called when
107 Ioncore has returned to the main loop.
109 <LI>You are absolute sure that C code outside your code has no
110 references to the object.
115 If there are no serious side effects from deferring destroying the
116 object or you're unsure whether it is safe to destroy the object
117 immediately, use <TT>mainloop_defer_destroy</TT>.
121 <H2><A NAME="SECTION00052000000000000000">
122 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> The types <TT>char*</TT> and <TT>const char*</TT> as function
123 parameters and return values</A>
127 The following rules should apply to using strings as return values and
128 parameters to functions.
131 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
132 <TR><TD ALIGN="LEFT">Type</TD>
133 <TD ALIGN="LEFT">Return value</TD>
134 <TD ALIGN="LEFT">Parameter</TD>
136 <TR><TD ALIGN="LEFT"><TT>const char*</TT></TD>
137 <TD ALIGN="LEFT">The string is owned by the called function
138 and the caller is only quaranteed short-term read access to the
140 <TD ALIGN="LEFT">The called function may only read the string during its execution.
141 For further reference a copy must be made.</TD>
143 <TR><TD ALIGN="LEFT"><TT>char*</TT></TD>
144 <TD ALIGN="LEFT">The string is the caller's responsibility and it
145 <SPAN CLASS="textit">must</SPAN> free it when no longer needed.</TD>
146 <TD ALIGN="LEFT">The called function may modify the string but the ``owner'' of
147 the string is case-dependant.</TD>
155 <DIV CLASS="navigation"><HR>
156 <!--Navigation Panel-->
157 <A NAME="tex2html133"
159 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
160 <A NAME="tex2html127"
161 HREF="ionnotes.html">
162 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
163 <A NAME="tex2html121"
165 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
166 <A NAME="tex2html129"
168 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
169 <A NAME="tex2html131"
171 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
173 <B> Next:</B> <A NAME="tex2html134"
174 HREF="node6.html">5 C coding style</A>
175 <B> Up:</B> <A NAME="tex2html128"
176 HREF="ionnotes.html">Ion: Notes for the</A>
177 <B> Previous:</B> <A NAME="tex2html122"
178 HREF="node4.html">3 The Lua interface</A>
179 <B> <A NAME="tex2html130"
180 HREF="node1.html">Contents</A></B>
181 <B> <A NAME="tex2html132"
182 HREF="node8.html">Index</A></B> </DIV>
183 <!--End of Navigation Panel-->