[svn-upgrade] Integrating new upstream version, ion3 (20071109)

[ion3.git] / doc / designnotes.tex

diff --git a/doc/designnotes.tex b/doc/designnotes.tex
deleted file mode 100644 (file)
index e22ed89..0000000
--- a/doc/designnotes.tex
+++ /dev/null
@@ -1,54 +0,0 @@
-\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}
-
-