--- libxds.tex 2001/08/09 12:58:08 1.5
+++ libxds.tex 2001/08/09 13:38:00 1.6
@@ -1,6 +1,6 @@
% -*- mode: LaTeX; fill-column: 75; -*-
%
-% $Id: libxds.tex,v 1.5 2001/08/09 12:58:08 simons Exp $
+% $Id: libxds.tex,v 1.6 2001/08/09 13:38:00 simons Exp $
%
\documentclass[a4paper,10pt,pointlessnumbers,bibtotoc]{scrartcl}
\usepackage[dvips,xdvi]{graphicx}
@@ -1001,6 +1001,62 @@
is not known in advance and the application cannot provide a buffer that's
guaranteed to suffice.
+\section{Frequently Asked Questions}
+
+\subsection{Why do we have separate encoding and decoding modes?}
+
+Some users complained about having to maintain separate XDS contexts for
+encoding and decoding. They wondered, why it is not possible to encode and
+decode with a single XDS context. The reason is that this limitatiton makes
+the XDS context structure and the programmer API for XDS much simpler. If
+we were able to use a single context for encoding and decoding, we had to
+maintain \emph{two} lists of registered engines per XDS context: One set of
+encoding engines and one set of decoding engines. Consequently, the
+\textsf{xds\_register()} function would need to take an additional
+parameter, which determines whether you're registering an encoding or an
+decoding engine. All this is not necessary in the current design, because
+one list of registered engines suffices.
+
+Another important topic is buffer management. The buffer handling in
+encoding mode is subtly different from that in encoding mode: The XDS
+context contains a buffer, the size of that buffer and a kind of ``current
+position'' pointer. When an engine stores, say, 8 bytes of encoded data in
+the buffer, \textsf{xds\_vencode()} will increase the ``current position''
+by 8 bytes --- the next encoding engine will append its encoded data at the
+end of the buffer. If the ``current position'' reaches the end of the
+buffer, the buffer is reallocated with an appropriately bigger size.
+
+In decoding mode, the same variables in the XDS context have a different
+meaning: Since the buffer is never going to be resized, the buffer size
+does not correspond to the size of the memory chunk that constitutes the
+buffer, it says how many bytes of information the buffer contains; it's the
+length of the contents. The ``current position'' is initialized at the
+beginning of the buffer and every time an engine claims to have decoded,
+say, 8 bytes from the buffer, the ``current position'' is increased by 8
+bytes towards the end of the buffer. If the ``current position'' reaches
+the end of the buffer's contents, an \textsf{XDS\_UNDERFLOW} error is
+returned.
+
+Buffer handling is different in encoding and decoding mode in so far as
+that in encoding mode, the initial buffer is empty and the current position
+moves with the end of the content, determining where new data should be
+appended. In decoding mode, the initial buffer is filled and the current
+position wanders from the beginning to the end of the content.
+
+Thus, if an XDS context should be used for both encoding and decoding, the
+library had to manage two different buffers because the encoding and
+decoding buffers have different semantics. Thus, the
+\textsf{xds\_setbuffer()} and \textsf{xds\_getbuffer()} routines would need
+an additional parameter in order to set the two buffers independently.
+
+Considering all that, we found that the current design greatly reduces the
+complexity of the implementation and of the API while putting the user only
+through minimum inconvenience.
+
+\subsection{What are those xds\_int-something types good for?}
+
+\subsection{Why do I have to register the engines manually?}
+
\begin{thebibliography}{xxx}
\bibitem{xdr} RFC 1832: ``XDR: External Data Representation Standard'',
|
