[Anet-checkins] CVS: Documentation/design/latex anetdesign.tex,1.5,1.6

[Christopher J. <cwj...@us...>]

Update of /cvsroot/anet/Documentation/design/latex
In directory usw-pr-cvs1:/tmp/cvs-serv4539

Modified Files:
	anetdesign.tex 
Log Message:
Don't worry I need to fix the dtd figure. 
Fixed a couple of formatting problems with the description
environment. The contents of an item can start on a new line with the
following hack:
\item[foo]\mbox{}\\ 
This will be on a separate line. :)

Index: anetdesign.tex
===================================================================
RCS file: /cvsroot/anet/Documentation/design/latex/anetdesign.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** anetdesign.tex	2002/01/05 16:46:35	1.5
--- anetdesign.tex	2002/01/06 19:54:01	1.6
***************
*** 85,89 ****
  \tableofcontents
  \listoffigures 
! \listoftables
  % do we need an abstract?
  %\clearpage
--- 85,90 ----
  \tableofcontents
  \listoffigures 
! 
! % \listoftables % we don't have tables yet...
  % do we need an abstract?
  %\clearpage
***************
*** 400,404 ****
  
  \begin{description}
! \item[Register/Unregister service]
  Given some service number, it
  registers that service for its calling module instance.  You can also
--- 401,405 ----
  
  \begin{description}
! \item[Register/Unregister service]\mbox{}\\
  Given some service number, it
  registers that service for its calling module instance.  You can also
***************
*** 410,414 ****
  command.
  
! \item[Send packet]
  Sends an ANet packet, query[3] or static data[4],
  to the ANet network.  The cluster group[5] where the packet will be
--- 411,415 ----
  command.
  
! \item[Send packet]\mbox{}\\
  Sends an ANet packet, query[3] or static data[4],
  to the ANet network.  The cluster group[5] where the packet will be
***************
*** 417,421 ****
  ANet packet" will be described in "Cluster Group Modules"[5].
  
! \item[Get Status]
  Will make the ANet daemon return a packet describing
  its current status.  The contents of this packet will be implementation
--- 418,422 ----
  ANet packet" will be described in "Cluster Group Modules"[5].
  
! \item[Get Status]\mbox{}\\
  Will make the ANet daemon return a packet describing
  its current status.  The contents of this packet will be implementation
***************
*** 424,428 ****
  going on in the daemon.
  
! \item[Get Status -- Start/Stop polling]
  From the time the daemon gets
  the "Start Polling" command to the time it gets the "Stop Polling"
--- 425,429 ----
  going on in the daemon.
  
! \item[Get Status -- Start/Stop polling]\mbox{}\\
  From the time the daemon gets
  the "Start Polling" command to the time it gets the "Stop Polling"
***************
*** 434,447 ****
  ignored.
  
! \item[Get Static Data]
  Given a primary and/or the secondary key, this
  will make ANet return all the static packets currectly stored locally
  that matches the key (or keys).
  
! \item[Change/Delete Static Data]
  Those commands will allow the module
  to change or delete some static packets currently stored locally.
  
! \item[Open TWDTC]
  Given the protocol, the ``unique address'' and the
  "subnet" of the other node, ANet will try to establish a Two-Way Data
--- 435,448 ----
  ignored.
  
! \item[Get Static Data]\mbox{}\mbox{}\\
  Given a primary and/or the secondary key, this
  will make ANet return all the static packets currectly stored locally
  that matches the key (or keys).
  
! \item[Change/Delete Static Data]\mbox{}\\
  Those commands will allow the module
  to change or delete some static packets currently stored locally.
  
! \item[Open TWDTC]\mbox{}\\
  Given the protocol, the ``unique address'' and the
  "subnet" of the other node, ANet will try to establish a Two-Way Data
***************
*** 453,466 ****
  can be used to identify the TWDTC with the other TWDTC commands.
  
! \item[Read/Write TWDTC]
  Read or write some data in the TWDTC.  This is
  similar to reading or writing data in a TCP socket.
  
! \item[Close TWDTC]
  Given an open TWDTC ID\footnote{If you know what
  "TWDTC ID" means, then you're ready to be a developer for ANet!},
  closes the identified channel.
  
! \item[Get Config]
  Returns the readeable tags in the configuration
  files \xs{sec:rtw}.  Each tag in the configuration files can have
--- 454,467 ----
  can be used to identify the TWDTC with the other TWDTC commands.
  
! \item[Read/Write TWDTC]\mbox{}\\
  Read or write some data in the TWDTC.  This is
  similar to reading or writing data in a TCP socket.
  
! \item[Close TWDTC]\mbox{}\\
  Given an open TWDTC ID\footnote{If you know what
  "TWDTC ID" means, then you're ready to be a developer for ANet!},
  closes the identified channel.
  
! \item[Get Config]\mbox{}\\
  Returns the readeable tags in the configuration
  files \xs{sec:rtw}.  Each tag in the configuration files can have
***************
*** 469,473 ****
  contain.  Otherwise, they remain to their default value.
  
! \item[Change Config]
  Allows the client connection module to change
  tags in the configuration file, it it has the right to do so.  The
--- 470,474 ----
  contain.  Otherwise, they remain to their default value.
  
! \item[Change Config]\mbox{}\\
  Allows the client connection module to change
  tags in the configuration file, it it has the right to do so.  The
***************
*** 644,648 ****
  \section{Cluster Group Modules} \label{sec:cgm}
  The Cluster Group Modules are used to duplicate, when needed, data
! between different clusters[1].
  
  \subsection{Design}
--- 645,649 ----
  \section{Cluster Group Modules} \label{sec:cgm}
  The Cluster Group Modules are used to duplicate, when needed, data
! between different clusters \xs{sec:rtw}.
  
  \subsection{Design}
***************
*** 659,663 ****
  
  \subsubsection{Input/Output for the Cluster Group Modules}
! As input, the Cluster Groups need two things each time their "main"
  function is called. First, they need a list of cluster IDs. Those are
  unique numbers that identify all the clusters you have to receive or
--- 660,664 ----
  
  \subsubsection{Input/Output for the Cluster Group Modules}
! As input, the Cluster Groups need two things each time their \texttt{main}
  function is called. First, they need a list of cluster IDs. Those are
  unique numbers that identify all the clusters you have to receive or
***************
*** 690,694 ****
  follows byte-ordering and memory alignment of the compiled
  deamon. Also, the structure is much more flexible than the External
! one\footnote{}.
  
  The AIPs are broken into two: the header and the data. The size of
--- 691,696 ----
  follows byte-ordering and memory alignment of the compiled
  deamon. Also, the structure is much more flexible than the External
! one\footnote{What I mean is that, most of the time, doing a simple
! typecasting is enough to retrieve the data you want.}.
  
  The AIPs are broken into two: the header and the data. The size of
***************
*** 737,742 ****
  \begin{fmpage}{\textwidth}
  \begin{verbatim}
! <!-- Cluster Group. Contains references to Clusters that compose 
!  that Cluster Group. -->
  <!ELEMENT ClusterGroup (ClusterRef)+>
  <!ATTLIST ClusterGroup %name; %moduleName; %args; %security;>
--- 739,743 ----
  \begin{fmpage}{\textwidth}
  \begin{verbatim}
! <!-- Cluster Group. Contains references to Clusters that compose that Cluster Group. -->
  <!ELEMENT ClusterGroup (ClusterRef)+>
  <!ATTLIST ClusterGroup %name; %moduleName; %args; %security;>
***************
*** 790,794 ****
  "definition kind" and the definition itself. The definition will be
  used be the Handshaking Protocol Modules to tell to the other node
! what are the security requirements of the cluster.
  
  The second function, the optional one, is used to do ``forced''
--- 791,795 ----
  "definition kind" and the definition itself. The definition will be
  used be the Handshaking Protocol Modules to tell to the other node
! what are the security xrequirements of the cluster.
  
  The second function, the optional one, is used to do ``forced''
***************
*** 852,856 ****
  be sent in a similar manner to the other Core Modules. Unused commands
  will be finally deleted if they were unused by all the Core
! Modules.(1)
  
  The input packets are AIPs. There is one buffer for all the cluster,
--- 853,859 ----
  be sent in a similar manner to the other Core Modules. Unused commands
  will be finally deleted if they were unused by all the Core
! Modules.\footnote{The Run-Time wrapper \xs{sec:rtw} will allow you to create as
! many new commands as you want. Actually, commands that are
! unrecognized by the wrapper will be sent to the Core Modules.}
  
  The input packets are AIPs. There is one buffer for all the cluster,
***************
*** 862,873 ****
  which are totally platform independant. The deamon will provide some
  functions to transform an AIP to an AEP, though the modules might have
! to set some values by themselves(2).
  
  \subsubsection{Core Modules}
  Here is a high-level description of the Core Modules that will be
! implemented for the first versions of ANet.(3)
! 
! Query Module
  
  This module will implement queries[1] for ANet. A query packet is sent
  to a connection only if the same packet was not sent recently and if
--- 865,885 ----
  which are totally platform independant. The deamon will provide some
  functions to transform an AIP to an AEP, though the modules might have
! to set some values by themselves.\footnote{For example, the
! \emph{Time-to-Live} exists only in the AEPs (for query AEPs), so it is up
! to the Query Module to fill the value. Note that the format or the
! AEPs will be very similar to the format of the AIP, though without
! memory alignment and with strict rules for byte ordering.}
  
  \subsubsection{Core Modules}
  Here is a high-level description of the Core Modules that will be
! implemented for the first versions of ANet.\footnote{The modules were
! already described in the development introduction. They don't really
! have a high-level design, and the low-level design will be covered
! during development. That's because it's too simple (Query Module) or
! too complex (Static Data and TWDT Module) to be worth the time
! investment. Don't worry, the modules will be thoroughly documented
! once a stable implementation will be done.}
  
+ \paragraph{Query Module}
  This module will implement queries[1] for ANet. A query packet is sent
  to a connection only if the same packet was not sent recently and if
***************
*** 878,884 ****
  sent, in the form of a simple checksum(4) and the origin of each
  packet.
- 
- Static Data Module
  
  This module will implement Static Data[2] in ANet. It will mostly use
  the hard disk to store the data, though it might need a larger cache
--- 890,895 ----
  sent, in the form of a simple checksum(4) and the origin of each
  packet.
  
+ \paragraph{Static Data Module}
  This module will implement Static Data[2] in ANet. It will mostly use
  the hard disk to store the data, though it might need a larger cache
***************
*** 886,891 ****
  packets.
  
! TWDT Module
! 
  This module will implement Anonymous Two-Way Data Transfers (TWDT[3])
  in ANet. Its input come only from the client commands[4] made for the
--- 897,901 ----
  packets.
  
! \paragraph{TWDT Module}
  This module will implement Anonymous Two-Way Data Transfers (TWDT[3])
  in ANet. Its input come only from the client commands[4] made for the
***************
*** 895,912 ****
  Communication[5], even though the caching of the queries it needs to
  produce is handled by the TWDT Module itself.
- 
- Managing Connections
  
  As input, the modules will always have a list of the connections, and
  their state. That list is kept in the parsed configuration
  file[5]. Here are the possible states.
- 
- Open 
-        The connection is open, thus it will accept input data and produce output data. 
- On Hold 
-        The connection cannot do any input or output, but will soon become either Open again or be Closed. 
- Closed 
-        The connection is forever closed. The connection will soon be removed from the connection list. 
  
  The Core Modules cannot, by themselves, change the state of a connection. Only Cluster Filter Modules[6] and by Handshaking Protocol
  Modules.
--- 905,922 ----
  Communication[5], even though the caching of the queries it needs to
  produce is handled by the TWDT Module itself.
  
+ \subsubsection{Managing Connections}
  As input, the modules will always have a list of the connections, and
  their state. That list is kept in the parsed configuration
  file[5]. Here are the possible states.
  
+ \begin{description}
+ \item[Open]\mbox{}\\ 
+   The connection is open, thus it will accept input data and produce output data. 
+ \item[On Hold]\mbox{}\\
+   The connection cannot do any input or output, but will soon become either Open again or be Closed. 
+ \item[Closed]\mbox{}\\
+   The connection is forever closed. The connection will soon be removed from the connection list. 
+ \end{description}
  The Core Modules cannot, by themselves, change the state of a connection. Only Cluster Filter Modules[6] and by Handshaking Protocol
  Modules.
***************
*** 1090,1093 ****
--- 1100,1217 ----
  \end{center}
  \label{fig:daemon} \caption{High-Level Structure of the ANet Daemon} 
+ \end{figure}
+ 
+ \begin{figure}
+ \begin{verbatim}
+ <!-- ******** Generic Entities ******** -->
+ <!ENTITY ANet.XMLVersion % 1.0a1>
+ 
+ <!-- ******* Attribute Entities ******* -->
+ 
+ <!-- Unique name for the element type. -->
+ <!ENTITY name % "name ID #REQUIRED">
+ 
+ <!-- Module name corresponding to that element.
+ A Module Instance will be created for each element with a module name. -->
+ <!ENTITY moduleName % "module CDATA #REQUIRED">
+ 
+ <!-- Arguments given to the module. They are POSIX-style arguments.
+ One-letter arguments: "-c -v" or "-cv".
+ String arguments: "-_-file="a.txt" (mentally delete underscore;
+ XML doesn't allow me to write that directly in XML comments).
+ You can mix both style of arguments. -->
+ <!ENTITY args % "args CDATA #IMPLIED">
+ 
+ <!-- Element security. This limits access for the Client Connection
+ Modules. The security attribute of an element is the one it has, if it's
+ not "no_change", otherwise it is the one from its closest ancestor with a
+ value other than "no_change". -->
+ <!ENTITY security % "access (r | w | rw | no_access | no_change) no_change">
+ 
+ <!-- ************ Elements ************ -->
+ 
+ <!-- #FIXED attributes are values that can be changed only at run-time.
+ Their default are discarded when parsing and replaced with the generated
+ value. -->
+ 
+ <!-- Root element -->
+ <!ELEMENT ANet (ClientConnection)+, BandwidthManager, (ClusterGroup)+, CoreModules, (Cluster)+>
+ <!ATTLIST ANet %security;>
+ 
+ <!-- Cluster Group. Contains references to Clusters that compose
+ that Cluster Group. -->
+ <!ELEMENT ClusterGroup (ClusterRef)+>
+ <!ATTLIST ClusterGroup %name; %moduleName; %args; %security;>
+ 
+ <!-- Cluster. Contains a Handshake Protocol and if needed
+ a Cluster Filter. -->
+ <!ELEMENT Cluster HandshakeProtocol, (ClusterFilter)?>
+ <!ATTLIST Cluster %id; %security;
+           id CDATA #FIXED>
+ 
+ <!-- Handshake Protocol. Contains a list of initial connections
+ (live connections once opened) -->
+ <!ELEMENT HandshakeProtocol (Connection)*>
+ <!ATTLIST HandshakeProtocol %moduleName; %args; %security;
+           minConnections CDATA "0"
+           maxConnections CDATA "-1">
+ 
+ <!-- Connection. Has a Connection Protocol and, if needed,
+ a Packet Protocol. -->
+ <!ELEMENT Connection (PacketProtocol)?, ConnectionProtocol, (DataTransform)*>
+ <!ATTLIST Connection %security;
+           status (open | on_hold | closed) #FIXED
+           id CDATA #FIXED
+           inBuffer CDATA #FIXED
+           outBuffer CDATA #FIXED>
+ 
+ <!-- Core Modules. Simply contains a list of CoreModule elements. -->
+ <!ELEMENT CoreModules (CoreModule)+>
+ <!ATTLIST CoreModules %security;>
+ 
+ <!-- Those are empty elements. If you want those elements to contain an XML
+ structure, then define an attribute that contains a reference to an external
+ XML document. -->
+ 
+ <!-- Client Connection Module -->
+ <!ELEMENT ClientConnection EMPTY>
+ <!ATTLIST ClientConnection %moduleName; %args; %security;>
+ 
+ <!-- Bandwidth Manager Module -->
+ <!ELEMENT BandwidthManager EMPTY>
+ <!ATTLIST BandwidthManager %moduleName; %args; %security;>
+ 
+ <!-- Core Module -->
+ <!ELEMENT CoreModule EMPTY>
+ <!ATTLIST CoreModule %moduleName; %args; %security;>
+ 
+ <!-- Cluster Filter Module -->
+ <!ELEMENT ClusterFilter EMPTY>
+ <!ATTLIST ClusterFilter %moduleName; %args; %security;>
+ 
+ <!-- Reference to a Cluster element -->
+ <!ELEMENT ClusterRef EMPTY>
+ <!ATTLIST ClusterRef
+           name IDREF #REQUIRED>
+ 
+ <!-- Packet Protocol Module -->
+ <!ELEMENT PacketProtocol EMPTY>
+ <!ATTLIST PacketProtocol %moduleName; %args; %security;>
+ 
+ <!-- Connection Protocol Module -->
+ <!ELEMENT ConnectionProtocol EMPTY>
+ <!ATTLIST ConnectionProtocol %moduleName; %args; %security;
+           id CDATA #FIXED
+           peerID CDATA #REQUIRED
+           subnet CDATA "Internet">
+ 
+ <!-- Data Transformation Module. Data Transformation Modules will be used
+ in ascending order of "order" for output (to the network), in descending
+ order for input (from the network). -->
+ <!ELEMENT DataTransform EMPTY>
+ <!ATTLIST DataTransform %moduleName; %args; %security;
+           order CDATA "-1">
+ \end{verbatim}
+ \label{fig:completedtd} \caption{ANet Complete DTD} 
  \end{figure}