Index: ossp-pkg/xds/docs/libxds.tex
RCS File: /v/ossp/cvs/ossp-pkg/xds/docs/libxds.tex,v
rcsdiff -q -kk '-r1.5' '-r1.6' -u '/v/ossp/cvs/ossp-pkg/xds/docs/libxds.tex,v' 2>/dev/null
--- libxds.tex	2001/08/09 12:58:08	1.5
+++ libxds.tex	2001/08/09 13:38:00	1.6
@@ -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'',