anet-checkins

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

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

Modified Files:
	anetdesign.tex 
Log Message:
added 2 other sections

Index: anetdesign.tex
===================================================================
RCS file: /cvsroot/anet/Documentation/design/latex/anetdesign.tex,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** anetdesign.tex	2002/01/02 20:40:36	1.3
--- anetdesign.tex	2002/01/03 19:02:39	1.4
***************
*** 11,17 ****
  % - If you add macros document them.
  % - If you use packages don't forget to add them in the directory.
! % - Please make your editor wrap the text.  It's easier to read. I 
  %   speak for myself, I like having a split screen with 2 views on the 
! %   document. Under emacs this easily done with the auto-fill-mode.
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  
--- 11,17 ----
  % - If you add macros document them.
  % - If you use packages don't forget to add them in the directory.
! % - Please make your editor wrap the text.   It's easier to read.  I 
  %   speak for myself, I like having a split screen with 2 views on the 
! %   document.  Under emacs this easily done with the auto-fill-mode.
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  
***************
*** 33,37 ****
  % Dimensions for 8.5" x 11" paper
  \textwidth 6.5in \textheight 9in
! % The default top margin is 1".  The following command adjusts it to 0.5".
  \topmargin -0.5in
  % There are two margin widths to allow for two-sided printing.
--- 33,37 ----
  % Dimensions for 8.5" x 11" paper
  \textwidth 6.5in \textheight 9in
! % The default top margin is 1".   The following command adjusts it to 0.5".
  \topmargin -0.5in
  % There are two margin widths to allow for two-sided printing.
***************
*** 57,66 ****
  \newcommand{\la}{\mathopen{<}} \newcommand{\ra}{\mathopen{>}}
  
- % trying to add the part command
- %\newcounter{partnum}
- %\newcommand{\part}[1]{\clearpage\thispagestyle{empty}%
- %\refstepcounter{partnum}\addcontentsline{toc}{partnum}{#1}%
- %\Huge{Part}}
- 
  % environment used for the DTD's
  \newsavebox{\fmbox}
--- 57,60 ----
***************
*** 69,77 ****
  {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}}
  
! % \newsavebox{\fmbox}
! % \newenvironment{fmpage}[1]
! % {\begin{lrbox}{\fmbox}\begin{minipage}{#1}}
! % {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}}
! 
  \newcounter{exnum}
  \newenvironment{example}[1]{\penalty-2000\vskip1.5\parskip
--- 63,67 ----
  {\end{minipage}\end{lrbox}\fbox{\usebox{\fmbox}}}
  
! % Environment used for examples
  \newcounter{exnum}
  \newenvironment{example}[1]{\penalty-2000\vskip1.5\parskip
***************
*** 95,99 ****
  \listoffigures 
  \listoftables
! %do we need an abstract?
  %\clearpage
  %\begin{abstract}
--- 85,89 ----
  \listoffigures 
  \listoftables
! % do we need an abstract?
  %\clearpage
  %\begin{abstract}
***************
*** 189,193 ****
  memory, mark it as temporary so its memory could be freed if memory is
  tight, and so on.\footnote{This was ``inspired'' by, you know
! \ldots\cite{applemem}}
  
  Second, whenever a function in a module is called, the module instance
--- 179,183 ----
  memory, mark it as temporary so its memory could be freed if memory is
  tight, and so on.\footnote{This was ``inspired'' by, you know
! \ldots\cite{apple-mem}}
  
  Second, whenever a function in a module is called, the module instance
***************
*** 246,250 ****
  \subsubsection{Configuration Management}
  The run-time wrapper will also manage the configuration files.  The
! configuration files are XML\cite{w3xml} files\footnote{Why XML? The
  first thing is that I don't want the ANet configuration files to be
  too difficult to edit.  Since ANet needs to have a structured
--- 236,240 ----
  \subsubsection{Configuration Management}
  The run-time wrapper will also manage the configuration files.  The
! configuration files are XML\cite{w3-xml} files\footnote{Why XML? The
  first thing is that I don't want the ANet configuration files to be
  too difficult to edit.  Since ANet needs to have a structured
***************
*** 335,350 ****
  \subsubsection{Clients and Daemon}
  From the point of view of its architecture, ANet is actually several
! programs. Only one program manages the network: the ANet
  daemon\footnote{You can have more than one ANet daemon in the same
  machine, but why? ANet is flexible enough to allow isolated network to
! coexist in the same system.}. It is consisting of the run-time wrapper
! \xs{sec:rtw} and of different modules. The daemon itself does not
! ``use'' the network. The programs that want to use an ANet network
! will have to communicate with the daemon in order to do so.  Those
  programs are the ANet Clients.
  
  The major advantage of doing so is that each time a developer wants to
  implement a new application for an anonymous network, that person does
! not need to re-implement the entire protocol again. This is similar to
  TCP, since it is being implemented in the operating system, the
  programmers won't have to re-implement TCP for each program that will
--- 325,340 ----
  \subsubsection{Clients and Daemon}
  From the point of view of its architecture, ANet is actually several
! programs.  Only one program manages the network: the ANet
  daemon\footnote{You can have more than one ANet daemon in the same
  machine, but why? ANet is flexible enough to allow isolated network to
! coexist in the same system.}.  It is consisting of the run-time wrapper
! \xs{sec:rtw} and of different modules.  The daemon itself does not
! ``use'' the network.  The programs that want to use an ANet network
! will have to communicate with the daemon in order to do so.   Those
  programs are the ANet Clients.
  
  The major advantage of doing so is that each time a developer wants to
  implement a new application for an anonymous network, that person does
! not need to re-implement the entire protocol again.  This is similar to
  TCP, since it is being implemented in the operating system, the
  programmers won't have to re-implement TCP for each program that will
***************
*** 353,375 ****
  \subsubsection{Services}
  Since ANet is a protocol, it doesn't know what kind of data it is
! distributing. So, the same network could be used for completely
  different things, yet it is not aware of it.
  
  But then, the clients ultimately care about what kind of data they are
! going to send and receive. As a result, each packet of information
! will be identified by a Service Number. A Service is a specific use of
  the network, and as a result, a group of information that can be
! consistently created, analyzed and modified. This is similar to a
! "port" in IP\cite{uscip}.
  
  \subsubsection{Interaction Summary}
  The Clients Connection Modules are modules that fully represent, by
! themselves, entire clients. Downwards \xs{sec:rtw}, they receive
  commands\footnote{This what inspired by HyperTalk, the programming
! language of HyperCard\cite{applehyp}. Here's an example: ask ``What is
  your name?''  if the result is "Benad" then answer ``Wow! I have the
  same name!''  Here, ``ask'' and ``answer'' are commands, while ``the result''
! is a function and ``is'' is an operator. This is not a joke!  } from the
! clients and they transfer them downwards in the daemon. Upwards
  \xs{sec:rtw}, they receive relevent data from the rest of the daemon
  and they tranfer that data to the proper clients.
--- 343,365 ----
  \subsubsection{Services}
  Since ANet is a protocol, it doesn't know what kind of data it is
! distributing.  So, the same network could be used for completely
  different things, yet it is not aware of it.
  
  But then, the clients ultimately care about what kind of data they are
! going to send and receive.  As a result, each packet of information
! will be identified by a Service Number.  A Service is a specific use of
  the network, and as a result, a group of information that can be
! consistently created, analyzed and modified.  This is similar to a
! "port" in IP\cite{usc-ip}.
  
  \subsubsection{Interaction Summary}
  The Clients Connection Modules are modules that fully represent, by
! themselves, entire clients.  Downwards \xs{sec:rtw}, they receive
  commands\footnote{This what inspired by HyperTalk, the programming
! language of HyperCard\cite{apple-hyp}.  Here's an example: ask ``What is
  your name?''  if the result is "Benad" then answer ``Wow! I have the
  same name!''  Here, ``ask'' and ``answer'' are commands, while ``the result''
! is a function and ``is'' is an operator.  This is not a joke!  } from the
! clients and they transfer them downwards in the daemon.  Upwards
  \xs{sec:rtw}, they receive relevent data from the rest of the daemon
  and they tranfer that data to the proper clients.
***************
*** 380,391 ****
  
  \begin{itemize}
! \item The user starts the ANet daemon. Thus, the clent connection
  module is started.
  \item The user starts the ANet client.
  \item The client connects itself to the client connection module.
! \item The client registers the services it will use. The client can
  receive and send data only for the services it registered for.
  \item The client connection module sends those registration requests
! to the rest of the daemon. Registration is actually made for the
  client connection module, so if more than one client connect to the
  module, then it has to remember which client requested what services.
--- 370,381 ----
  
  \begin{itemize}
! \item The user starts the ANet daemon.  Thus, the clent connection
  module is started.
  \item The user starts the ANet client.
  \item The client connects itself to the client connection module.
! \item The client registers the services it will use.  The client can
  receive and send data only for the services it registered for.
  \item The client connection module sends those registration requests
! to the rest of the daemon.  Registration is actually made for the
  client connection module, so if more than one client connect to the
  module, then it has to remember which client requested what services.
***************
*** 395,399 ****
  \item For all the data received from the network that have service
  numbers registered by the client connetion module, the daemon makes a
! copy of the data and sends it to the module. Also, for all commands
  that returns some value, the daemon sends the resulting data to the
  client connection module.
--- 385,389 ----
  \item For all the data received from the network that have service
  numbers registered by the client connetion module, the daemon makes a
! copy of the data and sends it to the module.  Also, for all commands
  that returns some value, the daemon sends the resulting data to the
  client connection module.
***************
*** 411,419 ****
  \item[Register/Unregister service]
  Given some service number, it
! registers that service for its calling module instance. You can also
! unregister some service you don't want to use anymore. If you pass a
  flag saying ``all services'', then the service number given will be
  ignored and all possible service numbers will be registered or
! unregistered. If you register all services, all other calls to this
  command will be ignored except the next ``unregister all services''
  command.
--- 401,409 ----
  \item[Register/Unregister service]
  Given some service number, it
! registers that service for its calling module instance.  You can also
! unregister some service you don't want to use anymore.  If you pass a
  flag saying ``all services'', then the service number given will be
  ignored and all possible service numbers will be registered or
! unregistered.  If you register all services, all other calls to this
  command will be ignored except the next ``unregister all services''
  command.
***************
*** 421,432 ****
  \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
! sent has to be specified. Use the "Get Config" command (read below) to
! know which cluster groups you can use. The format of the "internal
  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
  specific and outside the scope of the high-level design, though it
  will contain enough relevant information to let the user know what's
--- 411,422 ----
  \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
! sent has to be specified.  Use the "Get Config" command (read below) to
! know which cluster groups you can use.  The format of the "internal
  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
  specific and outside the scope of the high-level design, though it
  will contain enough relevant information to let the user know what's
***************
*** 437,442 ****
  the "Start Polling" command to the time it gets the "Stop Polling"
  command, the daemon will regularly send status packets the the client
! connection module. This is usefull for clients that want to monitor
! the status of the ANet daemon. With the "Start Polling" command, you
  can also specify what is the delay between when ANet will send the
  status packets, though if that value is too small, the command will be
--- 427,432 ----
  the "Start Polling" command to the time it gets the "Stop Polling"
  command, the daemon will regularly send status packets the the client
! connection module.  This is usefull for clients that want to monitor
! the status of the ANet daemon.  With the "Start Polling" command, you
  can also specify what is the delay between when ANet will send the
  status packets, though if that value is too small, the command will be
***************
*** 455,467 ****
  Given the protocol, the ``unique address'' and the
  "subnet" of the other node, ANet will try to establish a Two-Way Data
! Transfer [3] Channel (TWDTC) to the other node through the network. If
  ANet didn't already find which node to use as a proxy (that can have
  access to the protocol and subnet you specified), it might take some
! time to establich the connection. Use the ``Get status'' commands to
! know what's going on.  ANet will return a packet containing an ID that
  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.
  
--- 445,457 ----
  Given the protocol, the ``unique address'' and the
  "subnet" of the other node, ANet will try to establish a Two-Way Data
! Transfer [3] Channel (TWDTC) to the other node through the network.  If
  ANet didn't already find which node to use as a proxy (that can have
  access to the protocol and subnet you specified), it might take some
! time to establich the connection.  Use the ``Get status'' commands to
! know what's going on.   ANet will return a packet containing an ID that
  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.
  
***************
*** 473,484 ****
  \item[Get Config]
  Returns the readeable tags in the configuration
! files \xs{sec:rtw}. Each tag in the configuration files can have
! access rights, that is read, write or both. If specified, it affects
  the tag, and recursively overwriting the access rights of the tags it
! 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
  change can be saved to the hard disk, instead of being temporary, if
  the user has configured ANet to do so.
--- 463,474 ----
  \item[Get Config]
  Returns the readeable tags in the configuration
! files \xs{sec:rtw}.  Each tag in the configuration files can have
! access rights, that is read, write or both.  If specified, it affects
  the tag, and recursively overwriting the access rights of the tags it
! 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
  change can be saved to the hard disk, instead of being temporary, if
  the user has configured ANet to do so.
***************
*** 487,496 ****
  \subsection{Implementation Notes}
  There is no point of making one instance of the client connection
! module per connection to a client. Most instances should be made
! before having any connection to clients. Note that an instance cannot
  "instantiate itself" as the daemon receives a connection: the instance
  should exist to make whatever kind of connection it supports.  A
  client connection module doesn't have to allow all the commands
! allowed the the daemon. Actually, those modules can be very
  sophisticated, for example gateways[7]
  
--- 477,486 ----
  \subsection{Implementation Notes}
  There is no point of making one instance of the client connection
! module per connection to a client.  Most instances should be made
! before having any connection to clients.  Note that an instance cannot
  "instantiate itself" as the daemon receives a connection: the instance
  should exist to make whatever kind of connection it supports.  A
  client connection module doesn't have to allow all the commands
! allowed the the daemon.  Actually, those modules can be very
  sophisticated, for example gateways[7]
  
***************
*** 510,515 ****
  
  % maybe add a glossary
! % [1] Benad: "Run-Time Wrapper". Local link.
! % [2] University of Southern California , "Internet Protocol". External link. Cached.
  % [3] Benad: "Queries". Local link.
  % [4] Benad: "Static Data". Local link.
--- 500,505 ----
  
  % maybe add a glossary
! % [1] Benad: "Run-Time Wrapper".  Local link.
! % [2] University of Southern California , "Internet Protocol".  External link. Cached.
  % [3] Benad: "Queries". Local link.
  % [4] Benad: "Static Data". Local link.
***************
*** 525,553 ****
  \subsection{Design}
  The goal of the Data Transformation modules is to change some data
! into another form. Their most common use is compression and
  decompression, but they can also be used for encryption, or for any
  other function that has an inverse function\footnote{Actually, it
! could be used for things like tar\cite{fsftar}, MIME\cite{nwgmime},
! binhex\cite{nwgmimec}, or anything you can think of. Also, the input
  data for a transformation function could point to something outside
! the deamon, for example a database or the hard disk. So, it could be
  used to generate, if this is what you need.}.
  
! The data can be identified by a ``format'' tag. This 4-bytes value
! identifies the kind of data once it has been transformed. The "NULL"
! value identifies data that has not been transformed yet. The
  transformation function for each format use the input data as if it
! was untransformed data. Thus, the format tag has to be stored with the
  data before it is transformed to another kind of data\footnote{That
  is, you should store the previous format tag in a place that you can
! retrieve it once the data will be decoded back. Obviously, that's not
  needed if you assume that you're working with untransformed data.}.
  
! One instance is created for each Data Transform Module. Its
  initialization function should return a list of what format tags it
  supports, with both the actual, 4-byte tag and a Human-readable
! string, to make it easier to make the configuration file. It is
  assumed that for each supported format tag, both "transform to" and
! ``transform from'' functions are supported. Only one function is needed
  for each module, as the function will be passed the format tag, the
  "transformation direction" and a memory tag \xs{sec:rtw} that points to the
--- 515,543 ----
  \subsection{Design}
  The goal of the Data Transformation modules is to change some data
! into another form.  Their most common use is compression and
  decompression, but they can also be used for encryption, or for any
  other function that has an inverse function\footnote{Actually, it
! could be used for things like tar\cite{fsf-tar}, MIME\cite{nwg-mime},
! binhex\cite{nwg-mimec}, or anything you can think of.  Also, the input
  data for a transformation function could point to something outside
! the daemon, for example a database or the hard disk.  So, it could be
  used to generate, if this is what you need.}.
  
! The data can be identified by a ``format'' tag.  This 4-bytes value
! identifies the kind of data once it has been transformed.  The "NULL"
! value identifies data that has not been transformed yet.  The
  transformation function for each format use the input data as if it
! was untransformed data.  Thus, the format tag has to be stored with the
  data before it is transformed to another kind of data\footnote{That
  is, you should store the previous format tag in a place that you can
! retrieve it once the data will be decoded back.  Obviously, that's not
  needed if you assume that you're working with untransformed data.}.
  
! One instance is created for each Data Transform Module.  Its
  initialization function should return a list of what format tags it
  supports, with both the actual, 4-byte tag and a Human-readable
! string, to make it easier to make the configuration file.  It is
  assumed that for each supported format tag, both "transform to" and
! ``transform from'' functions are supported.  Only one function is needed
  for each module, as the function will be passed the format tag, the
  "transformation direction" and a memory tag \xs{sec:rtw} that points to the
***************
*** 560,580 ****
  
  The run-time wrapper will allow all modules to call any data
! transformation function. If you need any kind of security system, it
  has to be implemented within the data transformation module.
  
  \subsection{Implementation Notes}
  I think that relying on Inter-Module Communication for calling Data
! Transformation functions would be too complex. The run-time wrapper
  could have a single ``TrasformData'' function, to which you give all the
  needed data, without having to care to which module it relates to.  If
  two different modules can support the same format tag, than the one
! that will be used is undefined. So, if the data format could be
  implemented into various versions, it is recommended to store the
  version in the format tag itself\footnote{Please try to make your
! module ``fowards-compatible''. If you always use the same format tag
  accross versions, then it will be impossible to install two different
  versions of your module at the same time, which might be needed if
  your module is not backwards-compatible or if the latest version
! introduces new bug (don't worry, it always happen).}. Note that both
  the tag itself and its corresponding Human-readable string should be
  unique.
--- 550,570 ----
  
  The run-time wrapper will allow all modules to call any data
! transformation function.  If you need any kind of security system, it
  has to be implemented within the data transformation module.
  
  \subsection{Implementation Notes}
  I think that relying on Inter-Module Communication for calling Data
! Transformation functions would be too complex.  The run-time wrapper
  could have a single ``TrasformData'' function, to which you give all the
  needed data, without having to care to which module it relates to.  If
  two different modules can support the same format tag, than the one
! that will be used is undefined.  So, if the data format could be
  implemented into various versions, it is recommended to store the
  version in the format tag itself\footnote{Please try to make your
! module ``fowards-compatible''.  If you always use the same format tag
  accross versions, then it will be impossible to install two different
  versions of your module at the same time, which might be needed if
  your module is not backwards-compatible or if the latest version
! introduces new bug (don't worry, it always happen).}.  Note that both
  the tag itself and its corresponding Human-readable string should be
  unique.
***************
*** 582,591 ****
  \subsection{DTD}
  See the complete DTD for more information.
  \begin{figure}[!h]
  \begin{fmpage}{\textwidth}
  \begin{verbatim}
! <!-- 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; %security; order CDATA "-1">
--- 572,582 ----
  \subsection{DTD}
  See the complete DTD for more information.
+ 
  \begin{figure}[!h]
  \begin{fmpage}{\textwidth}
  \begin{verbatim}
! <!-- 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; %security; order CDATA "-1">
***************
*** 599,604 ****
  ANet.
  
  \section{Cluster Group Modules} \label{sec:cgm}
! Define data duplication between different clusters.
  
  \section{Cluster Filter Modules} \label{sec:clus}
--- 590,747 ----
  ANet.
  
+ \subsection{Design}
+ The goal of the ANet Client SDK is simplify to its maximum the
+ development of ANet clients. It does so by giving several tools within
+ a library.
+ 
+ \begin{itemize}
+ \item The actual connection with the a Client Connection Module in
+ ANet is done automatically by simply calling the "connect me"
+ function. Disconnection is also done with a simple function.
+ \item Sending and receiving data is simplified. You can send or
+ receive an array of packets with a single function call.
+ \item Functions are given to manage the stored static data[1] and to
+ read/change the configuration file. Functions are given to easily get
+ a list of the available cluster groups and connections without having
+ to "navigate" in the XML structure of the configuration file.
+ \item You can easily establish and use TWDT[2] connections, as if they
+ were BSD sockets.
+ \item Easily receive though callback functions messages from the
+ deamon (or actually the SDK itself) about the status of ANet, of the
+ network and so on.
+ \end{itemize}
+ 
+ Obviously, the number of functions implemented in the SDK will
+ increase, based on suggestions given by the client
+ developers. Extensive documentation and examples will be also be given
+ with the SDK.
+ 
+ \subsection{Implementation Notes}
+ The SDK functions should be distributed under LPGL[3], in the form of
+ a dynamic library\footnote{Programs that will use static linking with
+ the dynamic library from the ANet SDK must be distributed with a
+ license that ``permit modification of the work for the customer's own
+ use and reverse engineering for debugging such
+ modifications''\cite{fsf-lgpl}. What this means is that any part of
+ the ANet project, including the SDK, cannot be patented in any way...
+ }. Thus, developers can make clients that are not distributed under
+ GPL\cite{fsf-gpl} (the ANet deamon is distributed under GPL), for
+ example shareware or commercial.  It is very important for the SDK to
+ be easy to understand and well documented\footnote{This is something
+ that is usually lacking in most open-source projects: they are so
+ difficult to understand (or to simply interface another program with
+ them) that while their code is ``open'', their logic is ``closed''.
+ That's why I'm wasting... err...investing a lot of time writing the
+ documentation.  }. This means that examples of clients using the SDK
+ should be given. A lot of developer will have only the SDK as their
+ only point of view of ANet, so if it's not a good, it can give a bad
+ impression about the whole system.
+        
+ % [1] Benad: "Static Data". Local link.
+ % [2] Benad: "Anonymous Two-Way Data Transfers". Local link.
+ 
  \section{Cluster Group Modules} \label{sec:cgm}
! The Cluster Group Modules are used to duplicate, when needed, data
! between different clusters[1].
! 
! \subsection{Design}
! \subsubsection{Role of the Cluster Group Modules}
! Each module instance represents by itself a cluster group. When
! clients want to send data to the network, they have to send the data
! to one specific cluster group. Thus, one of the things that a Cluster
! Group Module has to do is that, given the packets coming from the
! clients, it has to send the incoming packets to the proper clusters.
! 
! Also, it is up to the Cluster Group Module to re-distribute the
! incoming packets from one cluster to another. This allows different
! clusters to exchange information.
! 
! \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
! send data to. You can get additional information about the clusters
! from the parsed configuration file. The IDs are not part of the
! configuration file \xs{sec:rtw}, but are generated as the file is parsed, and
! they are attributes as if they were written in the configuration file
! itself\footnote{So, the IDs must not be saved back to disk. They are
! re-generated each time the deamon is launched, except when it is
! ``resumed''.}. Also, they need an "input buffer", which is a list of
! ANet Internal Packets (AIP). Each packet is identified with the
! cluster ID it came from.
! 
! As output, they produce a list of AIPs, each one identified with the
! cluster ID it has to go to.
! 
! \subsubsection{The ANet Internal Packets (AIP)}
! Now it's a good time to introduce the most important data structure in
! the ANet deamon: the ANet Internal Packets, AIP in short.
! 
! An ANet Packet is very similar to packets in IP\cite{usc-ip}: they
! represent an independent block of information that cannot be broken
! down to be useful. You can split a large block of data into several
! ANet packets, as long as they contain enough information to be able to
! merge them back later in your client.
! 
! The ANet Internal Packet is a representation of an actual External
! Packet (AEP), but for use within the deamon. The goal of this
! structure is to make it easy to transform and process. Thus, it
! 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
! both the header and data are not fixed, but may have a limitation in
! size. By allowing the header to be of any size, we allow future
! versions of the ANet deamon to store additional information (at the
! end of the header) that can be safely ignored by previous versions of
! the modules.
! 
! So here is a list of what the header will, at minimum, contain:
! \begin{itemize}
! \item The \emph{total size} of the packet.
! \item The \emph{total header size}, which includes the space allocated for
! the value of the total size of the packet.
! \item The \emph{packet type}, which can be query, static, packet for a TWDTC,
! and so on.
! \item The \emph{service number}, which identifies what kind of data is
! contained in the packet (ftp, chat...).
! \item The \emph{origin or destination} of the packet. It's meaning depends on
! the context. Here, with Cluster Group Modules, they represent cluster
! IDs.
! \item \emph{Specific information} related to the packet type. For queries,
! you have a checksum. For static data, you have both the primary and
! secondary keys.
! \end{itemize}
! 
! Functions in the run-time wrapper will be given to all the modules to
! simplify access to the data contained in the AIPs.
! 
! \subsection{Implementation Notes}
! Even though it is expected that most Cluster Group Modules will work a
! lot with the Bandwidth Manager, I don't see the point of trying to add
! special access functions to the Bandwidth Manager. I'll make sure that
! the Inter-Module Communication \xs{sec:rtw} is simple enough to work with.
! Re-creating a new output buffer each time to fit the size of the
! buffer you want for the current function call might be slow. You
! should try to reuse as much as possible the same Memory Tag \xs{sec:rtw}, and
! resize it only when you find that it is not big enough.  The run-time
! wrapper will assume that the data is not modified when it is
! duplicated. Otherwise, the modified data is considered a new data,
! which might cause a slight speed degradation in the ANet Core.
! 
! \subsection{DTD}
! See the complete DTD for more information.
! \begin{figure}[!h]
! \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;>
! \end{verbatim}
! \end{fmpage}
! \caption{The Cluster Group Modules DTD} \label{fig:cgdtd}
! \end{figure}
  
  \section{Cluster Filter Modules} \label{sec:clus}