gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-05-30 00:11:26 +00:00
Code Issues Projects Releases Packages Wiki Activity

Initial revision

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@1 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
mccallum 1994-11-04 16:29:24 +00:00
commit 3a43130da6
248 changed files with 40027 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

135
Documentation/announce.texi Normal file
View file

@ -0,0 +1,135 @@
@chapter GNU Objective C Class Library
@c set the vars OBJECTS_VERSION and OBJECTS_GCC_VERSION
@include version.texi
The GNU Objective C Class Library, version @value{OBJECTS_VERSION}, is now
available.
@section What is the GNU Objective C Class Library?
It is a library of general-purpose, non-graphical Objective C objects
designed in the Smalltalk tradition. It includes collection objects for
maintaining groups of objects and C types, streams for I/O to various
destinations, coders for formating objects and C types to streams, ports
for network packet transmission, distributed objects (remote object
messaging), pseudo-random number generators, and time handling
facilities.
@ignore
So that developers of non-free, commercial programs can use the library,
the library is released under the GNU Library GPL.
So that it can easily be included in non-free, comercial software, the
library is released under the GNU Library GPL.
For more details, see the @samp{README} file that comes with the
distribution.
@end ignore
@c @section What's new in this release?
@include news.texi
@section Where can you get it? How can you compile it?
The libobjects-@value{OBJECTS_VERSION}.tar.gz distribution file has been
placed on @samp{prep.ai.mit.edu} in @samp{/pub/gnu}, and will be
appearing on the usual mirror sites.
@ignore
The library is available by anonymous ftp at URL:
@smallexample
ftp://prep.ai.mit.edu/pub/gnu/libobjects-@value{OBJECTS_VERSION}.tar.gz
@end smallexample
Since @samp{prep} is heavily loaded, you are encouraged to use GNU
mirror sites. A partial list of mirror sites is at the end of this
message.
@end ignore
The library requires gcc @value{OBJECTS_GCC_VERSION} or higher. The
library does not work with the NEXTSTEP 3.2 compiler because that
version of NeXT's cc cannot handle nested functions. Until a later
release from NeXT, NEXTSTEP users will have to install gcc. See the
@samp{INSTALL} file for more instructions about compiling and installing
the library.
The library has been successfully compiled and tested with the following
configurations:
@smallexample
mips-sgi-irix5.2
sparc-sun-sunos4.1.3
m68k-next-nextstep3.0
@end smallexample
Some previous snapshots of the library worked with these configurations,
but they haven't been tested recently:
@smallexample
i386-unknown-linux
i386-sun-solaris2.4
i386-unknown-sysv4.0
sparc-sun-solaris2.3
@end smallexample
It is known not to work with:
@smallexample
alpha-dec-osf
@end smallexample
The @samp{.tar} file is compressed with GNU gzip. Gzip can be obtained by
anonymous ftp at any of the GNU archive sites.
For info about FTP via email, send email to
@samp{ftpmail@@decwrl.dec.com} with no subject line, and two-line body
with line one @samp{help} and line two @samp{quit}.
The most recent (not necessarily tested) snapshots of the library will
be placed in @samp{ftp://alpha.gnu.ai.mit.edu/gnu}.
@display
Happy Hacking!
R. Andrew McCallum
mccallum@@gnu.ai.mit.edu
@end display
@format
[ Most GNU software is packed using the GNU `gzip' compression program.
Source code is available on most sites distributing GNU software.
For information on how to order GNU software on tape, floppy or cd-rom, or
printed GNU manuals, check the file etc/ORDERS in the GNU Emacs distribution
or in GNUinfo/ORDERS on prep, or e-mail a request to: gnu@@prep.ai.mit.edu
By ordering your GNU software from the FSF, you help us continue to
develop more free software. Media revenues are our primary source of
support. Donations to FSF are deductible on US tax returns.
The above software will soon be at these ftp sites as well.
Please try them before prep.ai.mit.edu as prep is very busy!
thanx -gnu@@prep.ai.mit.edu
ASIA: ftp.cs.titech.ac.jp, utsun.s.u-tokyo.ac.jp:/ftpsync/prep,
cair.kaist.ac.kr:/pub/gnu, ftp.nectec.or.th:/pub/mirrors/gnu
AUSTRALIA: archie.au:/gnu (archie.oz or archie.oz.au for ACSnet)
AFRICA: ftp.sun.ac.za:/pub/gnu
MIDDLE-EAST: ftp.technion.ac.il:/pub/unsupported/gnu
EUROPE: irisa.irisa.fr:/pub/gnu, ftp.univ-lyon1.fr:pub/gnu,
ftp.mcc.ac.uk, unix.hensa.ac.uk:/pub/uunet/systems/gnu,
src.doc.ic.ac.uk:/gnu, ftp.ieunet.ie:pub/gnu, ftp.eunet.ch,
nic.switch.ch:/mirror/gnu, ftp.informatik.rwth-aachen.de:/pub/gnu,
ftp.informatik.tu-muenchen.de, ftp.win.tue.nl:/pub/gnu,
ftp.funet.fi:/pub/gnu, ftp.denet.dk, ftp.stacken.kth.se, isy.liu.se,
ftp.luth.se:/pub/unix/gnu, ftp.sunet.se:/pub/gnu, archive.eu.net
SOUTH AMERICA: ftp.unicamp.br:/pub/gnu
WESTERN CANADA: ftp.cs.ubc.ca:/mirror2/gnu
USA: wuarchive.wustl.edu:/systems/gnu, labrea.stanford.edu,
ftp.digex.net:/pub/gnu, ftp.kpc.com:/pub/mirror/gnu, f.ms.uky.edu:/pub3/gnu,
jaguar.utah.edu:/gnustuff, ftp.hawaii.edu:/mirrors/gnu,
vixen.cso.uiuc.edu:/gnu, mrcnext.cso.uiuc.edu:/pub/gnu,
ftp.cs.columbia.edu:/archives/gnu/prep, col.hp.com:/mirrors/gnu,
gatekeeper.dec.com:/pub/GNU, ftp.uu.net:/systems/gnu
]
@end format

1286
Documentation/gnustep-base.texi Normal file
View file

File diff suppressed because it is too large Load diff

175
Documentation/install.texi Normal file
View file

@ -0,0 +1,175 @@
@c This is a generic INSTALL file for utilities distributions.
@c If this package does not come with, e.g., installable documentation or
@c data files, please ignore the references to them below.
@c set the vars OBJECTS_VERSION and OBJECTS_GCC_VERSION
@include version.texi
@ifset INSTALL_ONLY
This file documents the installation of the GNU Objective C
Class Library, @samp{libobjects}. Copyright (C) 1993, 1994 Free Software
Foundation, Inc. You may copy, distribute, and modify it freely as long
as you preserve this copyright notice and permission notice.
@chapter Installing @samp{libobjects}
@end ifset
To compile and install @samp{libobjects}:
@enumerate
@item
Install @samp{gcc}. The library requires gcc version
@value{OBJECTS_GCC_VERSION} or later.
@item
Configure the package for your system. In the directory that this file
is in, type @samp{./configure}. If you're using @samp{csh} on an old
version of System V, you might need to type @samp{sh configure} instead
to prevent @samp{csh} from trying to execute @samp{configure} itself.
If you are compiling the library for a NeXT machine, you have the choice
of using either the GNU or the NeXT Objective C runtime. You can
specify this by setting CFLAGS. For example:
@smallexample
CFLAGS=-fgnu-runtime ./configure
@end smallexample
The @samp{configure} shell script attempts to guess correct values for
various system-dependent variables used during compilation, and creates
the Makefile(s) (one in each subdirectory of the source directory). In
some packages it creates a C header file containing system-dependent
definitions. It also creates a file @samp{config.status} that you can
run in the future to recreate the current configuration.
Running @samp{configure} takes less than a minute or two. While it is
running, it prints some messages that tell what it is doing. If you
don't want to see the messages, run @samp{configure} with its standard
output redirected to @samp{/dev/null}; for example:
@smallexample
./configure >/dev/null
@end smallexample
To compile the package in a different directory from the one containing
the source code, you must use a version of make that supports the VPATH
variable, such as GNU make. @samp{cd} to the directory where you want
the object files and executables to go and run @samp{configure}.
@samp{configure} automatically checks for the source code in the
directory that @samp{configure} is in and in @samp{..}. If for some
reason @samp{configure} is not in the source code directory that you are
configuring, then it will report that it can't find the source code. In
that case, run @samp{configure} with the option @samp{--srcdir=DIR},
where DIR is the directory that contains the source code.
By default, @samp{make install} will install the package's files in
/usr/local/bin, /usr/local/lib, /usr/local/man, etc. You can specify
an installation prefix other than /usr/local by giving @samp{configure} the
option @samp{--prefix=PATH}. Alternately, you can do so by giving a value
for the @samp{prefix} variable when you run @samp{make}, e.g.,
@smallexample
make prefix=/usr/gnu
@end smallexample
You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you give @samp{configure}
the option @samp{--exec_prefix=PATH} or set the @samp{make} variable
@samp{exec_prefix} to PATH, the package will use PATH as the prefix for
installing programs and libraries. Data files and documentation will
still use the regular prefix. Normally, all files are installed using
the regular prefix.
You can tell @samp{configure} to figure out the configuration for your
system, and record it in @samp{config.status}, without actually
configuring the package (creating @samp{Makefile}s and perhaps a
configuration header file). To do this, give @samp{configure} the
@samp{--no-create} option. Later, you can run @samp{./config.status} to
actually configure the package. This option is useful mainly in
@samp{Makefile} rules for updating @samp{config.status} and
@samp{Makefile}. You can also give @samp{config.status} the
@samp{--recheck} option, which makes it re-run @samp{configure} with the
same arguments you used before. This is useful if you change
@samp{configure}.
@samp{configure} ignores any other arguments that you give it.
If your system requires unusual options for compilation or linking that
@samp{configure} doesn't know about, you can give @samp{configure}
initial values for some variables by setting them in the environment.
In Bourne-compatible shells, you can do that on the command line like
this:
@smallexample
CC='gcc -traditional' DEFS=-D_POSIX_SOURCE ./configure
@end smallexample
The @samp{make} variables that you might want to override with environment
variables when running @samp{configure} are:
(For these variables, any value given in the environment overrides the
value that @samp{configure} would choose:)
@table @samp
@item CC
C compiler program. Default is @samp{cc}, or @samp{gcc} if @samp{gcc}
is in your PATH.
@item INSTALL
Program to use to install files.
Default is @samp{install} if you have it, @samp{install.sh} otherwise.
@end table
(For these variables, any value given in the environment is added to
the value that @samp{configure} chooses:)
@table @samp
@item DEFS
Configuration options, in the form @samp{-Dfoo -Dbar ...}
@item LIBS
Libraries to link with, in the form @samp{-lfoo -lbar ...}
@end table
If you need to do unusual things to compile the package, we encourage
you to figure out how @samp{configure} could check whether to do them, and
mail diffs or instructions to the address given in the @samp{README} so we
can include them in the next release.
@item
Type @samp{make} to compile the package. If you want, you can override
the @samp{make} variables @samp{CFLAGS} and @samp{LDFLAGS} like this:
@smallexample
make CFLAGS=-O2 LDFLAGS=-s
@end smallexample
You will get some warnings from @samp{#warning} lines I've added to the
code. Ignore them.
You may get some warnings like @samp{stdobjects.m:0: warning:
`_OBJC_SELECTOR_TABLE' defined but not used}. Ignore them.
They are bogus warnings due to a bug in cc1obj.
You may get some warnings like @samp{ar: filename BinaryTreeEltNode.o
truncated to BinaryTreeEltNo}. Ignore them.
@item
If you want to compile the self-tests, cd to @samp{checks} and type
@samp{make}. If you want to compile the examples, cd to @samp{examples}
and type @samp{make}.
@item
Type @samp{make install} to install programs, data files, and
documentation.
@item
You can remove the program binaries and object files from the source
directory by typing @samp{make clean}. To also remove the Makefile(s),
and @samp{config.status} (all the files that @samp{configure} created),
type @samp{make distclean}.
The file @samp{configure.in} is used as a template to create
@samp{configure} by a program called @samp{autoconf}. You will only
need it if you want to regenerate @samp{configure} using a newer version
of @samp{autoconf}.
@end enumerate

1286
Documentation/libobjects.texi Normal file
View file

File diff suppressed because it is too large Load diff

131
Documentation/news.texi Normal file
View file

@ -0,0 +1,131 @@
@ifset NEWS_ONLY
@chapter News about GNU Objective C Class Library
@end ifset
@include version.texi
@section Noteworthy changes in version @samp{0.1}
@itemize
@item Renamed the library from @samp{libcoll} to @samp{libobjects}.
(See the end of the file @samp{DISCUSSION} for the background on this
name choice.) Several file names changed to reflect this. GNU class
interfaces are now included with @samp{objects} prefix,
e.g. @samp{#include <objects/BinaryTree.h>}.
@item Many new classes. Pseudo-random number classes Random, RNGBerkeley
and RNGAdditiveCongruential. New stream classes Stream, StdioStream and
MemoryStream. New coder classes Coder, TextCoder and BinaryCoder. New
network packet transmission classes Port and SocketPort. New remote
object messaging classes Connection, Proxy and ConnectedCoder. New
protocols Coding and Retaining. New, but unimplemented: Lock and
Locking. New but soon-to-disapppear: RetainingNotifier,
InvalidationListening.
@item Some bug fixes: Fixed the assert typo in Storage.m. The Time
class now compiles under Solaris. Fixed insertion bug in CircularArray.
NXStringTable_scan.l can now be compiled with lex, not just flex,
(thanks to Adam Fedor <adam@@bastille.rmnug.org>). Properly detect the
difference between gcc running under NEXTSTEP and NeXT's cc. Using
autoconf version 2.0. Renamed DelegateList to DelegatePool. Renamed
some collection hierarchy methods for better consistency.
@item Some directory reorganization so that NeXT-compatible files can be
included in the standard way, e.g. #include <objc/List.h>. Some other
NeXT-compatibility improvements: Changed @samp{GNU} prefix to @samp{NX}
in List and HashTable. New files zone.[hc] containing dummy stubs for
NeXT-compatible zone functions.
@end itemize
@c ====================================================================
@c Keep the next line just below the list of changes in most recent version.
@ifclear ANNOUNCE_ONLY
@section Noteworthy changes in verion @samp{940524}
@itemize
@item A NeXT-compatible NXStringTable object, thanks to Adam Fedor
<adam@@bastille.rmnug.org>.
@item
SplayTree and RBTree classes now operational. More methods in Time
class implemented.
@item
Some API cleanup: -delegateListList changed to -delegateListCollection.
-includesSameContents: changed to -contentsEqual:. -insertObject:atKey:
changed to -putObject:atKey:. See the ChangeLog for more detail.
@item
Configuration by autoconf in the self-tests directory. Configuration
script tests GCC nested functions. Configuration script detects
NEXTSTEP and makes the appropriate adjustments, including skipping the
NeXT-compatibility classes.
@item
Bug fixes: BinaryTree rotate methods fixed. Fixed the way
@code{ifNone:} and @code{ifAbsent:} functions were called. Fixed the
way long elements are printed. Added methods for preventing memory
leaks by unfinished enumerations: @code{-newEnumState} and
@code{-freeEnumState:}. Several bug fixes in List and Storage; changes
for better NeXT-compability. And more.
@end itemize
@section Noteworthy changes in version @samp{931026}
@itemize
@item
Installation using @samp{./configure} and @samp{autoconf}
@item
New BinaryTree and RBTree(unfinished) classes. Rewritten LinkedList
class.
@item
A new scheme for holding non-object elements in classes that require
object contents; EltNodeCollector class.
@item
Archiving with -write: and -read: methods. This involved removing the
ability to set the comparison function independent of content type.
@item
Removed COLL_NO_ELEMENT and friends. Now there are no arbitrary
restrictions on which long int's can be stored. Like in Smalltalk,
...ifAbsentCall: methods have been added to replace this functionalty.
@item
Added a LABMDA() macro for defining small functions in the arg position.
@item
Removed many ...perform: methods. Use instead the more flexible
...call: methods with LABMDA().
@item
Renamed ...Description: methods to ...Encoding: for better use of
already-defined objc keyword: @@encode().
@item
New in the Collecting protocol:
Filtered enumerating instead of filtered shallowCopy'ing.
Enumerations still safe when modifying the contents.
@item
The beginnings of documentation in libcoll.texi.
@item
Many bug fixes.
@item
...and more.
@end itemize
Also see the @samp{ChangeLog} file for more detail.
@end ifclear
@c end ifclear ANNOUNCE_ONLY

337
Documentation/readme.texi Normal file
View file

@ -0,0 +1,337 @@
@chapter GNU Objective-C Class Library README
@c set the vars OBJECTS_VERSION and GCC_VERSION
@include version.texi
Here is some introductory info to get you started:
@section Initial reading
The file @samp{ANNOUNCE} contains a very brief overview of the library.
It also tells you where to get the most recent version.
The file @samp{NEWS} has the library's feature history.
The file @samp{INSTALL} gives instructions for installing the library.
The file @samp{DISCUSSION} contains the archives of email discussions
about the library. It's a good place to read about the reasons for
some of the design decisions.
@section Preparing to write code
@ignore
Preliminary documentation is available via @samp{texinfo} in the files
@samp{libobjects.info} and @samp{libobjects.texi}. The info file was
created from the texi file using an modified version of @samp{makeinfo}
available by anonymous ftp from @samp{iesd.auc.dk:pub/ObjC}.
@end ignore
The documentation isn't much to speak of so far. Better documentation
will be forthcoming, but the library needs to settle first. For now I
recommend skipping libobjects.info and reading the header files
instead. The headers for the GNU classes are in ./objects; the headers
for the NeXT-compatible classes are in ./objects/next-include.
[NOTE: To compile code that uses NeXT compatibility classes, you'll want
to put @samp{XX/objects/next-include} in your include file search path.
Then, (unlike with the old libcoll), you can use #include <objc/List.h>
instead of #include <coll/List.h>.]
The overview of classes below should help you see the big picture as you
read the source.
@section The Class Heirarchy
Here is the class inheritance heirarchy. All protocols end with
"ing"; all collection protocols end with "Collecting". All collection
abtract superclasses (classes which are not usable without
subclassing) end with "Collection";
@example
Collection <Collecting>
Set
Bag
KeyedCollection <KeyedCollecting>
Dictionary
MappedCollector
IndexedCollection <IndexedCollecting>
Array
Stack
GapArray
CircularArray
Queue
Heap
LinkedList
BinaryTree
RBTree
EltNodeCollector
String
DelegatePool
LinkedListNode
LinkedListEltNode
BinaryTreeNode
BinaryTreeEltNode
RBTreeNode
RBTreeEltNode
Stream
StdioStream
MemoryStream
Coder
TextCoder
BinaryCoder
ConnectedCoder
Port <Coding>
SocketPort
Connection
Proxy <Coding>
Magnitude
Time
Random
RNGBerkeley <RandomGenerating>
RNGAdditiveCongruential <RandomGenerating>
@end example
@section Overview of the classes
The GNU classes included in this version of the library fall into five
categories: collections, magnitudes, streams, coders and distributed
object support.
@c There are several GNU protocols also. You can recognize the protocols
@c by their name: they all end with ``ing''.
@itemize
@item The collection objects all conform to the @samp{Collecting}
protocol. Reading @samp{./objects/Collecting.h} is a good place to
start. Protocols for collections that store their contents with keys
and with indices can be found in @samp{./objects/KeyedCollecting.h} and
@samp{./objects/IndexedCollecting.h} respectively. Examples of generic
collections are @samp{Set} and @samp{Bag}. The keyed collections are
@samp{Dictionary} and @samp{MappedCollector}. The classes @samp{Array},
@samp{Queue}, @samp{GapArray}, @samp{LinkedList}, @samp{BinaryTree},
@samp{RBTree} and @samp{SplayTree} are all indexed collections.
@item The public magnitude classes are @samp{Time} and @samp{Random}.
The @samp{Random} class works in conjunction with pseudo-random number
generators that conform to the @samp{RandomGenerating} protocol. The
conforming class @samp{RNGBerkeley} provides identical behavior to the
BSD random() function. The class @samp{RNGAdditiveCongruential} is an
implementation of the additive congruential method.
@item Stream objects provide a consistent interface for reading and
writing bytes. Read @samp{./objects/Stream.h} to get the general idea.
@samp{StdioStream} objects work with files, file descriptors, FILE
pointers and pipes to/from executables. @samp{MemoryStream} objects
work with memory buffers.
@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. See
@samp{./objects/Coder.h} for the abstract superclass interface; see
@samp{./objects/Coding.h} for the protocol adopted by objects that read
and write themselves using coders. The currently available concrete
coder classes are @samp{BinaryCoder}, for reading and writing a compact
stream of illegible bytes, and @samp{TextCoder}, for reading and writing
human-readable text (which you can also process with @samp{perl},
@samp{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.
Neither the stream or coder class heirarchies are very mature yet. I
threw them together because I needed them for distributed objects.
@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. The GNU distributed object
code does not work with the NeXT Objective C runtime. 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.]
To begin using distributed objects, you only need to know about
@samp{Connection} class. You can see the full interface in
@samp{./objects/Connection.h}. The long list of methods may be a little
daunting, but actually, a lot can be done with just a few key methods:
@smallexample
- (Connection*) newRegisteringAtName: (const char*)name
withRootObject: anObj;
For registering your server object with the network.
- (void) runConnection;
For running the connection object returned by the above
method, so that your server can start handling requests from
clients.
- (Proxy*) rootProxyAtName: (const char*)name
onHost: (const char*)host;
For connecting to a remote server. You get a proxy object for
the remote server object, which, for messaging purposes, you
can treat as if it were local.
@end smallexample
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.
- Send messages with vararg arguments.
- 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 Where else to look
@subsection Examples
A few simple example programs can be found in @samp{./examples}.
Read and enjoy. To compile them (after having compiled the library),
type @samp{make} in the @samp{examples} directory.
@itemize
@item @samp{dictionary.m} demonstrates the basic features of the
Dictionary object.
@item @samp{stdio-stream.m} creates a StdioStream object that points to
a file, writes to the file, then reads from the file.
@item @samp{textcoding.m} shows how you can archive an object to a file
in a human-readable text format, and then read it back in again. This
format is handy for editing archived objects with a text editor, and is
great when you want to modify/create an archive using a scripting
language like @samp{perl} or @samp{awk}.
@item @samp{first-server.m} and @samp{first-client.m} show the
distributed object version of ``Hello, world''.
@item @samp{second-server.m} and @samp{second-client.m} contain a more
complex demonstration of distributed objects, with multiple clients,
connection delegates, and invalidation notification.
@item @samp{port-server.m} and @samp{port-client.m} show a simple use of
Port objects. Be warned, however, the interface to Port objects will
likely change in the near future.
@end itemize
@subsection Test Programs
Some of the programs I've used to test the library are in
@samp{./checks}. Many of them are pretty messy, (desperately trying to
tickle that late night bug), but at least they show some code that works
when the library compiles correctly. I'm looking for a volunteer to
write some nicely organized test cases using @samp{dejagnu}. Any
takers?
@section Coming Soon...
More improvements to the library are on the way. Closest in the
pipeline are String objects and better allocation/deallocation
conventions for objects.
These improvements will bring some changes to the current interfaces:
(1) Almost everywhere that the current methods now take (char*)
arguments, the new methods will take (String*) arguments. (2) The use
of the method @samp{free} will be abolished and replaced by new
methods.
I'm trying to get these changes in place as soon as possible so that
you don't end up writing too much code that uses the old (i.e. current)
interfaces.
Meanwhile, please use the library! The small amount of changes you may
need to make won't be difficult, and the earlier I get usability
suggestions and bug reports, the sooner the fixes will come.
@section How can you help?
@itemize
@item Read the projects and questions in the @samp{TODO} file. If you
have any useful comments mail them to me!
@item
Give me feedback! Tell me what you like; tell me what you think
could be better. Send me bug reports.
@item
Donate classes. If you write classes that fit in the libobjects
framework, I'd be happy to include them.
@end itemize
@example
Happy hacking!
Andrew McCallum
mccallum@@gnu.ai.mit.edu
@end example

4030
Documentation/texinfo.tex Normal file
View file

File diff suppressed because it is too large Load diff

324
Documentation/todo.texi Normal file
View file

@ -0,0 +1,324 @@
@ifset TODO_ONLY
@chapter GNU Objective-C Class Library To Do list, and Questions.
@c set the vars GOBJC_VERSION and GCC_VERSION
@include version.texi
@end ifset
@section Projects Looking for Volunteers
If you think you can do one of these projects, please let me know. Your
help is greatly appreciated! Send email to
@samp{mccallum@@gnu.ai.mit.edu}.
@itemize
@item Make the GNU Objective C runtime properly initialize the class
pointer of statically-created string objects (i.e. the string objects
created with the syntax @samp{@@"This is a constant string object"}).
See the relevant comments in gcc/objc-act.c. Once we get this working
I'll release the suite of String classes that I've already written.
Please! Someone? I want to do this soon so that we can get the ensuing
interface changes done before too many people write code based on the
current deprecated char-pointer interfaces.
@item Make the GNU Objective C runtime thread-safe. (Again, someone?
We really need this.)
@item Write a test-suite for the library. Use dejagnu.
@item Write a proper name server for SocketPort's. Currently we're just
hashing the name to a socket port number---we could get unwanted hash
collisions. This will also allow us to name a SocketPort after it's
been created.
@item Make SocketPort more reliable than UDP.
@item Add some features to the compiler:
@enumerate
@item You can't add __attribute__'s to methods. I want to use:
@smallexample
- (int) writeFormat: (const char *)format, ...
__attribute__ ((format (printf, 1, 2)));
- (int) readFormat: (const char *)format, ...
__attribute__ ((format (scanf, 1, 2)));
@end smallexample
@item I would like to be able to use a function name/pointer as an
argument to @@encode() and get a type string like the selector types.
@end enumerate
@item Notification registration classes, notification classes.
@item Write more/better random number generators. Make them conform to
the protocol <RandomGenerating>. See RNGAdditiveCongruential.
@item Write user-visible random number classes in the spirit of the
@samp{Random} class. Look at Smalltalk's ProbabilityDistribution
classes, and think about replacing the @samp{Random} class with
something more like these. How about Poisson and Gaussian distributions
also?
@end itemize
@section My To Do's
@itemize @bullet
@item Many code fixes and cleanups, indicated with @samp{xxx} in the source.
@item In remote object messaging, send exceptions back to the requestor.
I'm waiting for gcc 2.7 exceptions.
@item Add Coding methods to all the other collection classes.
@item Find method for detecting NeXT vs GNU runtime. Put it in
@samp{configure.in} and define @samp{NeXT_runtime}.
@item
The LAMBDA macro doesn't work on all systems. Request a change to gcc
that make something like LAMBDA work on all systems.
@item
Possibly change @code{-(int)compare:anObject} for Collection. How
should non-Indexed collections be ordered?
@item
Think about restructuring the Collection heirarchy. We need an abstract
class for collections that are ordered, but whose order is fixed by the
-compare: method, i.e. not user-settable. We need non-mutable version
of the classes. The implementation of this stuff is crying out for
multiple inheritance or protocols-with-implementation!
@item
Finish HashTable.m. Implement freeKeys:values: (What is this supposed
to do anyway?). Handle archiving of atom string, "%", keys.
@item
Finish Time.m. Many methods are not yet implemented.
@item
Write a good hash function for floats and doubles.
@c This from
@c libg++.texi: @code{unsigned int foldhash(double x);} a hash function for
@c doubles that exclusive-or's the first and second words of x, returning
@c the result as an integer.
@item
Many implementations could be made more efficient. Libobjects hasn't
been efficiency tuned at all. Overridding more methods in certain
classes could make things more efficient (especially EltNodeCollector).
SplayTree's could be done using top-down splaying. collhash could be
completely reimplemented. ...and a lot more...
@item
Fix bugs that arise when double's are included in the elt union.
@item
Fix all the subclassResponsibility comments in objects/*.h
@c @item
@c Look at __gcc_bcmp in libgcc2.c.
@item
I will finish libobjects documentation.
@end itemize
@c ==================================================================
@section Questions
I would greatly appreciate your feedback on the questions
below. Please email your thoughts to mccallum@@gnu.ai.mit.edu.
@itemize @bullet
@item
I want to put method names in texinfo indices, but the colons in the
method names are interfering with info's notion of menu item names and
node names. Help. Any ideas? (Kresten?)
@item
I need to read through al the enumState code again and clean it up.
Perhaps we'd like an Iterator class to use as a wrapper around the
enumState functionality? The NIH Class Library organizes things this
way.
@item
Should we keep the -safe... enumeration methods? They sure do add a
lot of clutter to the protocols. If we got rid of them people would
have to alloc an Array, copy the contents, and free the Array
themselves.
@item
What would people think about removing the ...Object methods, and just
having the ...Element methods instead? It might be a bit more difficult
to use, but it would reduce clutter significantly. The ...Element
methods are more efficient to use anyway, since most ...Object methods
are wrappers around ...Element calls. I'm not sure what I think we
should do.
Here's an idea: Define the ...Object methods as macros. But we need a
new macro scheme that works for methods instead of functions. We would
need something with the following functionality:
@smallexample
#define [REC replaceObject: OLDOBJ with: NEWOBJ] \
([REC replaceElement:(elt)(OLDOBJ) with:(elt)(NEWOBJ)].id_u)
@end smallexample
The issue of macros for methods has been mentioned in email
found in the gnu-objc-issues archive, in the file @samp{preprocessor}.
@item
It would be nice to have more error checking on the types going in and
out of a collection. When some code tries to put a float into a
collector initialized to hold integers, it would be nice to catch that.
Perhaps just some macros that will do the appropriate checks? It would
also be nice if elt's returned from methods were automatically casted to
the correct type.
It might be good to use something like this (from the gcc
PROJECTS file):
@example
* A way of defining a structure containing a union, in which the choice
of union alternative is controlled by a previous structure component.
Here is a possible syntax for this.
struct foo @{
enum @{ INT, DOUBLE @} code;
auto union @{ case INT: int i; case DOUBLE: double d;@} value : code;
@};
@end example
This has the disadvantage that now elt's will take up more than one
word.
What I would prefer is something more radical: Some efficient way to
enable int's, float's to receive Objective-C messages. Then I wouldn't
have to worry about any of these horrible elt typing issues; I wouldn't
have to worry about all the ...Object ...Element method name
duplication; I wouldn't have to worry about the inefficiency of having
all the ...Object methods just be covers for the ...Element methods.
Lots of other Objective-C code would find this useful too. It has
the advantage of fixing the previous question also (about removing the
...Element ...Object method duplication). We need Objective-C objects
that can live on the stack.
For now, I've worked out a ObjC++ solution to this with constructors and
casting operators. Now I'm just waiting for Kresten to finish ObjC++.
@item
Perhaps we should put more safety checks into LinkedList,
BinaryTree, etc: Check that node is not already part of another
collection (by checking that neighbor pointers are nil?) In method
"insertObject:newObject after:oldObject" make sure that oldObject is a
member of self. ...It seems that there is a lot of potential for
nasty bugs with mistakes like these.
@item
HashTable.m (-initKeyDesc:valueDesc:capacity:) I tried to make it
portable, but I didn't try very hard. Anyone want to send in fixes?
@item
I fixed -emptyCopy in all the subclasses, but the -emptyCopy scheme
seems pretty fragile. How about calling -initFoo: inside -emptyCopy?
This way we avoid having yet another method in which instance vars
must be initialized to some consistent state. -allocCopy would never
even get called. <<ObjC insiders: This is a less well-expressed
version of what we've just been discussing in email.>>
@item
The situation with LinkedListNode and LinkedListEltNode, (and the
analagous classes for BinaryTree's and RBTree's) are just crying out
for multiple inheritance. Anyone have ideas that are prettier than my
quick fix using #include ? Anyone have an alternate organization that
doesn't need multiple inheritance?
@item
Somes classes, like RBTree, depend on a certain ordering of elements
to maintain internal consistency. How should we define the behavior
of methods whose names imply that the user can set the ordering of
elements independent of these constraints? (like -appendElement: or
-insertElement:atIndex: for instance). I see three possibilities:
@enumerate
@item The methods do what they say. Give the user the power to
override the default ordering.
@item The methods do not do what they say, but call addElement:
instead. This lets the class maintain its internal consistency, but
it has the potential to be a bit confusing to the user. What would
happen if the user sent a sort message to such a class, for instance?
@item The methods trigger a -shouldNotImplement: error. This solution
perhaps best expresses the reality of the situation, but it's a bit
strange for a class to signal an error on a method which is in a
protocol the class conforms to.
@end enumerate
Currently I'm using solution #1 (in most classes?).
@item
I created libobjects.texi by copying libg++.texi. Some of the text
is taken verbatim. Is this a problem?
@item
If you don't like the organization of the documentation and you have
suggestions for changes, please say so now, not after it's all been
written.
@item
Does anyone really miss the ability to set the comparison function
independent of the element encoding? If it's really important we can
come up with ways to do this and still be able to archive comparison
functions.
@item
Something like this needed?
- elementDidChange: (elt*)elementPtr;
Currently you have to remove, change, add, for some classes.
@c -------------------------------------------------------------------
@c @section Questions leftover from last release
@item
Opinions on the error reporting scheme? See also
@samp{checks/test05.m}. This error reporting scheme will most likely
change completely as soon as gcc gets exception handling.
@item
Should I include _comparison_function as an instance variable of
Collection? Putting it back in could make some things more efficient,
but several classes don't have configurable comparisonFunction's
(i.e. String, LinkedList, BinaryTree, RBTree), so they don't need it.
@item
I've been told that GNU filenames should be 14 chars or less. I
don't want to abbreviate my classnames, but I think using .h
@@interface files with names different than the class name is even
worse. ** I want to keep my unabbreviated filenames!! ** What to do,
what to do... I can't believe that *all* GNU classnames will be
limited to 12 characters forever and ever---disgusting.
@end itemize
@c ==================================================================
@section Changes I'd like in the Objective-C runtime and gcc:
@itemize @bullet
@item
Make OBJC_MALLOC() and friends public. Have the runtime and
Object.m use them. See objc-malloc.[hm].
@item
Give hash.[hc] functionality more like collhash.[hc], i.e.:
Add hash_node_for_key() to hash.h and hash.c.
Change hash_next() so that more than one enumeration of the contents
can happen concurrently.
How about removing cache as a parameter to the hashing functions in
hash.h and hash.c. Do the masking on the result of the hash function.
This seems much neater to me.
@item
Add a way of defining a structure containing a union, in which the choice
of union alternative is controlled by a previous structure component.
(See gcc @samp{PROJECTS} file.)
@end itemize