Move documentation files from egcs/gcc/objc.

From-SVN: r22461

libobjc/README

+
+GNU Objective C notes
+*********************
+
+This document is to explain what has been done, and a little about how
+specific features differ from other implementations.  The runtime has
+been completely rewritten in gcc 2.4.  The earlier runtime had several
+severe bugs and was rather incomplete.  The compiler has had several
+new features added as well.
+
+This is not documentation for Objective C, it is usable to someone
+who knows Objective C from somewhere else.
+
+
+Runtime API functions
+=====================
+
+The runtime is modeled after the NeXT Objective C runtime.  That is,
+most functions have semantics as it is known from the NeXT.  The
+names, however, have changed.  All runtime API functions have names
+of lowercase letters and underscores as opposed to the
+`traditional' mixed case names.  
+	The runtime api functions are not documented as of now.
+Someone offered to write it, and did it, but we were not allowed to
+use it by his university (Very sad story).  We have started writing
+the documentation over again.  This will be announced in appropriate
+places when it becomes available.
+
+
+Protocols
+=========
+
+Protocols are now fully supported.  The semantics is exactly as on the
+NeXT.  There is a flag to specify how protocols should be typechecked
+when adopted to classes.  The normal typechecker requires that all
+methods in a given protocol must be implemented in the class that
+adopts it -- it is not enough to inherit them.  The flag
+`-Wno-protocol' causes it to allow inherited methods, while
+`-Wprotocols' is the default which requires them defined.
+
+
++initialize 
+===========
+
+This method, if defined, is called before any other instance or class
+methods of that particular class.  This method is not inherited, and
+is thus not called as initializer for a subclass that doesn't define
+it itself.  Thus, each +initialize method is called exactly once (or
+never if no methods of that particular class is never called).
+Besides this, it is allowed to have several +initialize methods, one
+for each category.  The order in which these (multiple methods) are
+called is not well defined.  I am not completely certain what the
+semantics of this method is for other implementations, but this is
+how it works for GNU Objective C.
+
+
+Passivation/Activation/Typedstreams
+===================================
+
+This is supported in the style of NeXT TypedStream's.  Consult the
+headerfile Typedstreams.h for api functions.  I (Kresten) have
+rewritten it in Objective C, but this implementation is not part of
+2.4, it is available from the GNU Objective C prerelease archive. 
+   There is one difference worth noting concerning objects stored with
+objc_write_object_reference (aka NXWriteObjectReference).  When these
+are read back in, their object is not guaranteed to be available until
+the `-awake' method is called in the object that requests that object.
+To objc_read_object you must pass a pointer to an id, which is valid
+after exit from the function calling it (like e.g. an instance
+variable).  In general, you should not use objects read in until the
+-awake method is called.
+
+
+Acknowledgements
+================
+
+The GNU Objective C team: Geoffrey Knauth <gsk@marble.com> (manager),
+Tom Wood <wood@next.com> (compiler) and Kresten Krab Thorup
+<krab@iesd.auc.dk> (runtime) would like to thank a some people for
+participating in the development of the present GNU Objective C.
+
+Paul Burchard <burchard@geom.umn.edu> and Andrew McCallum
+<mccallum@cs.rochester.edu> has been very helpful debugging the
+runtime.   Eric Herring <herring@iesd.auc.dk> has been very helpful
+cleaning up after the documentation-copyright disaster and is now
+helping with the new documentation.
+
+Steve Naroff <snaroff@next.com> and Richard Stallman
+<rms@gnu.ai.mit.edu> has been very helpful with implementation details
+in the compiler.
+
+
+Bug Reports
+===========
+
+Please read the section `Submitting Bugreports' of the gcc manual
+before you submit any bugs.

libobjc/README.threads

+==============================================================================
+README.threads - Wed Nov 29 15:16:24 EST 1995
+------------------------------------------------------------------------------
+
+Limited documentation is available in the THREADS file.
+
+This version has been tested on Sun Solaris, SGI Irix, and Windows NT.
+It should also work on any single threaded system.
+
+Thanks go to the following people for help test and debug the library:
+
+	Scott Christley, scottc@ocbi.com
+	Andrew McCallum, mccallum@cs.rochester.edu
+
+galen
+gchunt@cs.rochester.edu
+
+Any questions, bug reports, etc should be directed to:
+
+Scott Christley, scottc@ocbi.com
+
+Please do not bug Galen with email as he no longer supports the code.
+
+==============================================================================
+Changes from prior releases (in revered chronological order):
+------------------------------------------------------------------------------
+
+* Fixed bug in copy part of sarray_realloc.  I had an < which should
+  have been <=. (Bug report from Scott).
+
+------------------------------------------------------------------------------
+
+* Support for DEC OSF/1 is definitely broken.  My programs always
+  seg-fault when I link with libpthreads.a.
+
+* Thread id's are no longer int's, but are instead of type
+  _objc_thread_t which is typedef'ed from a void *.  An invalid thread
+  id is denoted by NULL and not -1 as before.
+
+------------------------------------------------------------------------------
+
+* Renamed thread-winnt.c to thread-win32.c to better reflect support
+  for the API on both Windows NT and Windows 95 platforms.  
+  (Who knows, maybe even Win32s :-).
+
+* Fixed bugs in Win32 support as per report from Scott Christley.
+
+* Fixed bug in sarray_get as per report from Scott Christley.
+
+	

libobjc/THREADS.MACH

+This readme refers to the file thr-mach.c.
+
+Under mach, thread priorities are kinda strange-- any given thread has
+a MAXIMUM priority and a BASE priority.  The BASE priority is the
+current priority of the thread and the MAXIMUM is the maximum possible
+priority the thread can assume.  The developer can lower, but never
+raise the maximum priority.
+
+The gcc concept of thread priorities is that they run at one of three
+levels;  interactive, background, and low.
+
+Under mach, this is translated to:
+
+interactive -- set priority to maximum
+background  -- set priority to 2/3 of maximum
+low         -- set priority to 1/3 of maximum
+
+This means that it is possible for a thread with the priority of
+interactive to actually run at a lower priority than another thread
+with a background, or even low, priority if the developer has modified
+the maximum priority.
+
+