@chapter GNU Objective-C Class Library

@c set the vars GNUSTEP_BASE_VERSION and GCC_VERSION
@include version.texi

The Gnustep Base Library (libgnustep-base) is a library of
general-purpose, non-graphical Objective C objects written by Andrew
McCallum.  What `libg++' is to GNU's C++, `libgnustep-base' is to GNU's
Objective C.

The library features collection objects for maintaining groups of
objects and C types, strings for handling collections of characters,
streams for I/O to various destinations, coders for formating objects
and C types to byte streams, ports for network packet transmission,
distributed objects (remote object messaging), pseudo-random number
generators, and time handling facilities.

@itemize @bullet

@item
The heirarchy of collection objects are similar in spirit to Smalltalk's
collections.  A deep inheritance heirarchy provides good uniformity of
method names across different collection classes.  All collections can
hold simple C types (such as int's and floats) as well as Objects.  The
collection classes include simple collections (Set, Bag), collections
with contents accessible by unordered keys (Dictionary,
MappedCollector), collections with ordered contents (Array, LinkedList,
Stack, Queue, Heap, BinaryTree, RBTree, SplayTree, GapArray).  There is
also a DelegatePool object that can forward messages it receives to an
arbitrary number of delegate objects.

@item
String objects...

@item
Stream objects provide a consistent interface for reading and writing
bytes.  `StdioStream' objects work with files, file descriptors, FILE
pointers and pipes to/from executables.  `MemoryStream' objects work
with memory buffers that grow automatically as needed.  For all Stream
objects there are methods for writing/reading arbitrary n-length
buffers, newline-terminated lines, and printf-style strings.

@item
Coders provide a formatted way of writing to Streams.  After a coder is
initialized with a stream, the coder can encode/decode Objective C
objects and C types in an architecture-independent way.  The currently
available concrete coder classes are `BinaryCoder', for reading and
writing a compact stream of illegible bytes, and `TextCoder', for
reading and writing human-readable structured textual representation
(which you can also process with `perl', `awk', or whatever scripting
language you like).

Coders and streams can be mixed and matched so that programmers can
choose the destination and the format separately.

@item
The distributed object support classes are @samp{Connection},
@samp{Proxy}, @samp{ConnectedCoder}, @samp{Port} and @samp{SocketPort}.
This version of the distributed objects only works with sockets.  A Mach
port back-end should be on the way.

[NOTE: The GNU distributed object facilities have the same ease-of-use
as NeXT's; be warned, however, that they are not compatible with each
other.  They have different class heirarchies, different instance
variables, different method names, different implementation strategies
and different network message formats.  You cannot communicate with a
NeXT NXConnection using a GNU Connection.  NXConnection creates NXProxy
objects for local objects as well as remote objects; GNU Connection
doesn't need and doesn't create proxies for local objects.  NXProxy asks
it's remote target for the method encoding types and caches the results;
GNU Proxy gets the types directly from the local GNU "typed selector"
mechanism and has no need for querying the remote target or caching
encoding types.  The NXProxy for the remote root object always has name
0 and, once set, you cannot change the root object of a NXConnection;
the GNU Proxy for the remote root object has a target address value just
like all other Proxy's, and you can change the root object as many times
as you like.  See the "lacking-capabilities" list below for a partial
list of things that NXConnection can do that GNU Connection cannot.]

Here is a partial list of what the current distributed objects system
can do:
@smallexample
* It can pass and return all simple C types, including char*, float 
  and double, both by value and by reference.
* It can pass structures by value and by reference, return 
  structures by reference.  The structures can contain arrays.
* It obeys all the type qualifiers: oneway, in, out, inout, const.
* It can pass and return objects, either bycopy or with proxies.
  An object encoded multiple times in a single message is properly
  decoded on the other side.
* Proxies to remote objects are automatically created as they are
  returned.  Proxies passed back where they came from are decoded
  as the correct local object.
* It can wait for an incoming message and timeout after a 
  specified period.
* A server can handle multiple clients.
* The server will ask its delegate before making new connections.
* The server can make call-back requests of the client, and keep 
  it all straight even when the server has multiple clients.
* A client will automatically form a connection to another client 
  if an object from the other client is vended to it. (i.e. Always 
  make a direct connection rather than forwarding messages twice, 
  once into the server, from there out to the other client.)
* The server will clean up its connection to a client if the client 
  says goodbye (i.e. if the client connection is freed).
* When the connection is being freed it will send a invalidation 
  notification message to those objects that have registered for
  such notification.
* Servers and clients can be on different machines of different
  architectures; byte-order and all other architecture-dependent
  nits are taken care of for you.  You can have SPARC, i386, m68k, 
  and MIPS machines all distributed-object'ing away together in
  one big web of client-server connections!
@end smallexample

Here is a partial list of what the current distributed objects system
does *not* do: 
@smallexample
* Run multi-threaded.
* Detect port deaths (due to remote application crash, for example) 
  and do something graceful.
* Send exceptions in the server back to the client.
* Return structures by value.
* Use Mach ports, pass Mach ports, pass Mach virtual memory.
* Send messages more reliably than UDP.  It does detect reply
  timeouts and message-out-of-order conditions, but it's reaction 
  is simply to abort.
* Claim to be thoroughly tested.
@end smallexample

@end itemize

@section Getting It, and Compiling It

The library is available by anonymous ftp at URL:
@smallexample
ftp://prep.ai.mit.edu/pub/gnu/libgnustep-base-@value{GNUSTEP_BASE_VERSION}.tar.gz
@end smallexample
Since @samp{prep} is heavily loaded, you are encouraged to use GNU
mirror sites.

The most recent (not necessarily tested) snapshots of the library will
be placed at @samp{ftp://alpha.gnu.ai.mit.edu/gnu}.

@include machines.texi

@section GNUStep

The @samp{libgnustep-base} library already contains many of the GNUStep
common classes: List, HashTable, Storage, NXStringTable.  In the future
it will also contain the foundation kit classes for GNUStep.  Progress
is already being made on this front.

@section Contact:
@example
Andrew McCallum
mccallum@@gnu.ai.mit.edu
@end example

@bye