ionnotes/node5.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2
   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 -->
   8 <HTML>
   9 <HEAD>
  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">
  15
  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">
  19
  20 <LINK REL="STYLESHEET" HREF="ionnotes.css">
  21
  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">
  26 </HEAD>
  27
  28 <BODY >
  29
  30 <DIV CLASS="navigation"><!--Navigation Panel-->
  31 <A NAME="tex2html133"
  32   HREF="node6.html">
  33 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
  34 <A NAME="tex2html127"
  35   HREF="ionnotes.html">
  36 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
  37 <A NAME="tex2html121"
  38   HREF="node4.html">
  39 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
  40 <A NAME="tex2html129"
  41   HREF="node1.html">
  42 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
  43 <A NAME="tex2html131"
  44   HREF="node8.html">
  45 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
  46 <BR>
  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  &nbsp; <B>  <A NAME="tex2html130"
  54   HREF="node1.html">Contents</A></B>
  55  &nbsp; <B>  <A NAME="tex2html132"
  56   HREF="node8.html">Index</A></B>
  57 <BR>
  58 <BR></DIV>
  59 <!--End of Navigation Panel-->
  60 <!--Table of Child-Links-->
  61 <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></A>
  62
  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>
  69 </UL>
  70 <!--End of Table of Child-Links-->
  71 <HR>
  72
  73 <H1><A NAME="SECTION00050000000000000000">
  74 <SPAN CLASS="arabic">4</SPAN> Miscellaneous design notes</A>
  75 </H1>
  76
  77 <P>
  78
  79 <H2><A NAME="SECTION00051000000000000000">
  80 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">1</SPAN> Destroying WObj:s</A>
  81 </H2>
  82
  83 <P>
  84 To keep Ion's code as simple as possible yet safe, there are restrictions
  85 when the WObj
  86 <TT>destroy_obj</TT><A NAME="619"></A>
  87 function that calls watches, the deinit routine and frees memory may
  88 be called directly. In all other cases the
  89 <TT>defer_destroy</TT><A NAME="620"></A>
  90 function should be used to defer the call of <TT>destroy_obj</TT> until
  91 Ioncore returns to its main event loop.
  92
  93 <P>
  94 Calling the <TT>destroy_obj</TT> function directly is allowed in the
  95 following cases:
  96
  97 <UL>
  98 <LI>In the deinit handler for another object. Usually managed objects
  99       are destroyed this way.
 100 </LI>
 101 <LI>The object was created during the current call to the function
 102       that wants to get rid of the object. This is the case, for example,
 103       when the function created a frame to manage some other object but for
 104       some reason failed to reparent the object to this frame.
 105 </LI>
 106 <LI>In a deferred action handler set with
 107       <TT>defer_action</TT><A NAME="621"></A>.
 108       Like deferred destroys, other deferred actions are called when
 109       Ioncore has returned to the main loop.
 110 </LI>
 111 <LI>You are absolute sure that C code outside your code has no
 112       references to the object.
 113 </LI>
 114 </UL>
 115
 116 <P>
 117 If there are no serious side effects from deferring destroying the
 118 object or you're unsure whether it is safe to destroy the object
 119 immediately, use <TT>defer_destroy</TT>.
 120
 121 <P>
 122
 123 <H2><A NAME="SECTION00052000000000000000">
 124 <SPAN CLASS="arabic">4</SPAN>.<SPAN CLASS="arabic">2</SPAN> The types <TT>char*</TT> and <TT>const char*</TT> as function
 125   parameters and return values</A>
 126 </H2>
 127
 128 <P>
 129 The following rules should apply to using strings as return values and
 130 parameters to functions.
 131
 132 <P>
 133 <TABLE CELLPADDING=3 BORDER="1" WIDTH="100%">
 134 <TR><TD ALIGN="LEFT">Type</TD>
 135 <TD ALIGN="LEFT">Return value</TD>
 136 <TD ALIGN="LEFT">Parameter</TD>
 137 </TR>
 138 <TR><TD ALIGN="LEFT"><TT>const char*</TT></TD>
 139 <TD ALIGN="LEFT">The string is owned by the called function
 140        and the caller is only quaranteed short-term read access to the
 141        string.</TD>
 142 <TD ALIGN="LEFT">The called function may only read the string during its execution.
 143        For further reference a copy must be made.</TD>
 144 </TR>
 145 <TR><TD ALIGN="LEFT"><TT>char*</TT></TD>
 146 <TD ALIGN="LEFT">The string is the caller's responsibility and it
 147        <SPAN  CLASS="textit">must</SPAN> free it when no longer needed.</TD>
 148 <TD ALIGN="LEFT">The called function may modify the string but the ''owner'' of
 149        the string is case-dependant.</TD>
 150 </TR>
 151 </TABLE>
 152
 153 <P>
 154
 155 <P>
 156
 157 <DIV CLASS="navigation"><HR>
 158 <!--Navigation Panel-->
 159 <A NAME="tex2html133"
 160   HREF="node6.html">
 161 <IMG WIDTH="37" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next" SRC="next.png"></A>
 162 <A NAME="tex2html127"
 163   HREF="ionnotes.html">
 164 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up" SRC="up.png"></A>
 165 <A NAME="tex2html121"
 166   HREF="node4.html">
 167 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous" SRC="prev.png"></A>
 168 <A NAME="tex2html129"
 169   HREF="node1.html">
 170 <IMG WIDTH="65" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="contents" SRC="contents.png"></A>
 171 <A NAME="tex2html131"
 172   HREF="node8.html">
 173 <IMG WIDTH="43" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="index" SRC="index.png"></A>
 174 <BR>
 175 <B> Next:</B> <A NAME="tex2html134"
 176   HREF="node6.html">5 C coding style</A>
 177 <B> Up:</B> <A NAME="tex2html128"
 178   HREF="ionnotes.html">Ion: Notes for the</A>
 179 <B> Previous:</B> <A NAME="tex2html122"
 180   HREF="node4.html">3 The Lua interface</A>
 181  &nbsp; <B>  <A NAME="tex2html130"
 182   HREF="node1.html">Contents</A></B>
 183  &nbsp; <B>  <A NAME="tex2html132"
 184   HREF="node8.html">Index</A></B> </DIV>
 185 <!--End of Navigation Panel-->
 186
 187 </BODY>
 188 </HTML>