gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-22 16:33:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

new file containing docs in gdomap.h (not formatted there for gsdoc nor usable if so)

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@20059 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Adrian Robert 2004-09-14 02:16:55 +00:00
parent 06bcb753db
commit 1819e5edbe
1 changed files with 309 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

309
Tools/gdomap.gsdoc Normal file
View file

@ -0,0 +1,309 @@
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.1//EN" "http://www.gnustep.org/gsdoc-1_0_1.xml">
<gsdoc base="gdomap" up="BaseTools">
<head>
<title>gdomap documentation</title>
<author name="Richard Frith-Macdonald">
<email address="richard@brainstorm.co.uk">
richard@brainstorm.co.uk
</email>
</author>
<copy>1998 Free Software Foundation, Inc.</copy>
</head>
<body>
<front><contents /></front>
<chapter id="_main">
<heading>gdomap</heading>
<p>
The gdomap daemon is used by GNUstep programs to look up distributed
objects of processes running on the local machine as well as across
the network.
</p>
<p>
Usually the gdomap daemon is started at system boot time and binds
itself to port 538. (See the GNUstep Build Guide for a sample
startup script.) It expects to receive fixed-size request packets
for registering, deregistering, and looking up distributed objects
servers. The response packets vary in length depending on the type
and content of the information requested. In addition, limited
support for federation is provided by a rudimentary gdomap-gdomap
communications protocol.
</p>
<p>
What follows is a description of gdomap from a developer
perspective. For information pertinent for users, such as how to
configure and start up gdomap, please see the man page for more
information ("man 8 gdomap").
</p>
<p>
The name server is intended to work with both the UDP and the TCP
protocols. It is intended that the TCP interface be used by
GNUstep programs, while the UDP interface is intended primarily
for communication between name servers on different machines.
</p>
<section>
<heading>Usage Scenario</heading>
<p>
A complete distributed-objects "conversation" between a client
and a server looks like the outline below. The gdomap daemon
only plays a role in the "pre-" and "post-" phases. Everything
else is conducted "peer-to-peer" between the two GNUstep
processes.
</p>
<deflist>
<term>Pre-conversation</term>
<desc>
<enum>
<item>
Server registers an object as being available as the
'root object' on a particular port with a specific
name.
</item>
<item>
Client looks up a port by name.
</item>
</enum>
</desc>
<term>Conversation</term>
<desc>
<enum>
<item>
Client connects to the port and asks for the root
object.
</item>
<item>
Server returns proxy to root object.
</item>
<item>
Client then proceeds to send messages to the object.
</item>
<item>
Server sends message responses except where methods
are declared 'oneway'.
</item>
<item>
The server may also send messages to the client and
have the client send responses.
</item>
<item>
Eventually, the client or the server disconnects by
invalidating port or connection or just exiting.
</item>
</enum>
</desc>
<term>Post-conversation</term>
<desc>
On shutdown, the server unregisters the service name and
port it used.
</desc>
</deflist>
</section>
<section>
<heading>How it Works and Why</heading>
<p>
The fixed size of a request packet was chosen for maximum
ease and speed of implementation of a non-blocking name server.
The server knows how much it needs to read and can therefore
usually do a read as a single operation since it doesn't have
to read a little, figure out request length, allocate a buffer,
and read the rest.
</p>
<p>
The server name length (bytes) is specified - no assumptions
should be made about whether the name contains nul characters
or indeed about the name at all. This is future-proofing.
</p>
<p>
Why UDP as well as TCP?
The OpenStep specification says that a connection may be
established to any host on the local network which supplys a
named service if the host name is specified as '*'.
</p>
<p>
This means that the application must poll to see if it can
find a server with the name it wants. The polling could take
a huge amount of time!
</p>
<p>
To make this all easier - the server is capable of supplying
a list of those hosts on the local network which it knows to
have (or have had) a name server running on them.
</p>
<p>
The application then need only poll those name servers to find
the service it wants.
</p>
<p>
However - to give the application a list of hosts, the name
server must have got the information from somewhere.
To gather the information the server has to poll the machines
on the net which would take ages using TCP since attempts to
talk to machines which are down or do not exist will take a
while to time out.
</p>
<p>
To make things speedy, the server sends out GDO_PROBE requests
on UDP to all the machines on the net when it starts up.
Each machine which has a name server notes that the new name
server has started up and sends back a GDOPREPLY packet so
that the new name server will know about it.
</p>
<p>
Things are never perfect though - if a name server dies, the
other name servers won't know, and will continue to tell
applications that it is there.
</p>
<p>
Port type codes - these are used to say what the port is for so
that clients can look up only the names that are relevant to them.
This is to permit the name server to be used for multiple
communications protocols (at the moment, tcp or udp) and for
different systems (distributed objects or others).
This guarantees that if one app is using DO over UDP, its services
will not be found by an app which is using DO over TCP.
</p>
</section>
<section>
<heading>Communications Protocol</heading>
<p>
The communications protocol is identical for both TCP and UDP
and consists of a simple request-response sequence.
</p>
<p>
Each request is a single message consisting of -
</p>
<enum>
<item>
a single byte request type
</item>
<item>
a single byte giving name length,
</item>
<item>
a single byte specifying the type of port being registered
or looked up, or a nul byte for probe operations.
</item>
<item>
a single nul byte.
</item>
<item>
a four byte port number in network byte order must be
present for register operations, otherwise this is zero.
</item>
<item>
a service name of 0 to GDO_NAME_MAX_LEN bytes (or two IP
addresses in network byte order and an optional list of
additional addresseso for probe operations)
</item>
<item>
0 to GDO_NAME_MAX_LEN nul bytes padding the service name to
its full size.
</item>
<item>
a terminating nul byte.
</item>
</enum>
<p>
The total is always sent in a packet with everything after the
service name (except the final byte) cleared to nul bytes.
</p>
<p>
Each response consists of at least 4 bytes and depends on the
corresponding Request Type and where it came from as follows -
</p>
<deflist>
<term>GDO_LOOKUP</term>
<desc>
Looks up the server name and returns its port number.
Response is the port number in network byte order, or zero
if the named server was not registered.
</desc>
<term>GDO_REGISTER</term>
<desc>
Registers the given server name with a port number. This
service is only available to processes on the same host as
the name server. Response is the port number in network
byte order, or zero if the named server was already
registered.
</desc>
<term>GDO_UNREG</term>
<desc>
Un-register the server name and return old port number. If
the server name is of length zero, and the port is non-zero
then all names for the port are unregistered. This service
is only available to a process on the same host as this name
server. Response is the old port number in network byte
order, or zero if the name could not be un-registered. If
multiple names were unregistered the response is the port
for those names.
</desc>
<term>GDO_SERVERS</term>
<desc>
Return a list of the known servers on the local net.
Response is an unsigned long (in network byte order) saying
how many servers the name server knows about, followed by a
list of their IP addresses in network byte order. NB. This
response may not be possible over UDP as the response length
may exceed the maximum UDP packet size.
</desc>
<term>GDO_NAMES</term>
<desc>
Return a list of registered names known to the server.
Response is an unsigned long (in network byte order) saying
how many bytes of data are to follow, followed by a list of
the names each preceeded by the name length (a single byte)
and port type (a byte). NB. This response may not be
possible over UDP as the response length may exceed the
maximum UDP packet size.
</desc>
</deflist>
<p>
The following are used for communications between name servers -
</p>
<deflist>
<term>GDO_PROBE</term>
<desc>
Requests a response Passes two IP addresses in the name
field - first the address of the sender, next that of the
recipient. The packet may (optionally) include a variable
number of addresses (as specified by the name length minus
the size of the two addresses), each of which is an internet
address on which the sender is also listening. For a
request from a name server via UDP there is no response, but
a GDO_REPLY request is sent. For a request from a
non-name-server, or a TCP connect, the response is the port
number of this server in network byte order.
</desc>
<term>GDO_PREPLY</term>
<desc>
Replies to a GDO_PROBE via UDP from a name server. The
format of the message is as for GDO_PROBE. No response is
sent.
</desc>
</deflist>
</section>
</chapter>
</body>
</gsdoc>