designnotes.tex

   1 \section{Miscellaneous design notes}
   2
   3 \subsection{Destroying \type{WObj}:s}
   4
   5 To keep Ion's code as simple as possible yet safe, there are restrictions
   6 when the \type{WObj}
   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
  10 \code{defer_destroy}\index{defer-destroy@\code{defer_destroy}}
  11 function should be used to defer the call of \code{destroy_obj} until
  12 Ioncore returns to its main event loop.
  13
  14 Calling the \code{destroy_obj} function directly is allowed in the
  15 following cases:
  16 \begin{itemize}
  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
  24       \code{defer_action}\index{defer-action@\code{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.
  29 \end{itemize}
  30
  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{defer_destroy}.
  34
  35 \subsection{The types \code{char*} and \code{const char*} as function
  36   parameters and return values}
  37
  38 The following rules should apply to using strings as return values and
  39 parameters to functions.
  40
  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
  45        string. &
  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. \\
  52 \end{tabularx}
  53
  54