home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-3.iso / OpenStep / systems / gnustep / sources / libobjects-0.1.19.README < prev    next >
Encoding:
Text File  |  1996-01-22  |  12.3 KB  |  292 lines
  1. GNU Objective-C Class Library README
  2. ************************************
  3.  
  4. Here is some introductory info to get you started:
  5.  
  6. Initial reading
  7. ===============
  8.  
  9.    The file `ANNOUNCE' contains a very brief overview of the library.
  10. It also tells you where to get the most recent version.
  11.  
  12.    The file `NEWS' has the library's feature history.
  13.  
  14.    The file `INSTALL' gives instructions for installing the library.
  15.  
  16. Preparing to write code
  17. =======================
  18.  
  19.    Preliminary documentation is available via `texinfo' in the files
  20. `libobjects.info' and `libobjects.texi'.  The info file was created
  21. from the texi file using an modified version of `makeinfo' available by
  22. anonymous ftp from `iesd.auc.dk:pub/ObjC'.
  23.  
  24.    The documentation isn't much to speak of so far.  Better
  25. documentation will be forthcoming, but the library needs to settle
  26. first.  For now I recommend skipping libobjects.info and reading the
  27. header files instead.  The headers for the GNU classes are in
  28. `./objects'; the headers for the NeXT-compatible classes are in
  29. `./objc' and `./Foundation'.
  30.  
  31.    The overview of classes below should help you see the big picture as
  32. you read the source.
  33.  
  34. The Class Heirarchy
  35. ===================
  36.  
  37.    Here is the class inheritance heirarchy.  All protocols end with
  38. "ing"; all collection protocols end with "Collecting".  All collection
  39. abtract superclasses (classes which are not usable without subclassing)
  40. end with "Collection";
  41.  
  42.      NSObject
  43.        Collection <Collecting>
  44.          Set
  45.            Bag
  46.          KeyedCollection <KeyedCollecting>
  47.            Dictionary
  48.              MappedCollector
  49.              IndexedCollection <IndexedCollecting>
  50.                Array
  51.                  Stack
  52.                  GapArray
  53.                  CircularArray
  54.                    Queue
  55.                  Heap
  56.                LinkedList
  57.                BinaryTree
  58.                RBTree
  59.                EltNodeCollector
  60.                String
  61.        LinkedListNode
  62.          LinkedListEltNode
  63.        BinaryTreeNode
  64.          BinaryTreeEltNode
  65.          RBTreeNode
  66.            RBTreeEltNode
  67.        Stream
  68.          StdioStream
  69.          MemoryStream
  70.        Coder
  71.          TextCoder
  72.          BinaryCoder
  73.            ConnectedCoder
  74.        RetainingNotifier
  75.          Port
  76.            SocketPort
  77.          Connection
  78.        Magnitude
  79.          Time
  80.        Random
  81.        RNGBerkeley <RandomGenerating>
  82.        RNGAdditiveCongruential <RandomGenerating>
  83.      DelegatePool
  84.      Proxy
  85.  
  86. Overview of the classes
  87. =======================
  88.  
  89.    The GNU classes included in this version of the library fall into six
  90. categories: collections, strings, magnitudes, streams, coders and
  91. distributed object support.
  92.  
  93.    * The collection objects all conform to the `Collecting' protocol.
  94.      Reading `./objects/Collecting.h' is a good place to start.
  95.      Protocols for collections that store their contents with keys and
  96.      with indices can be found in `./objects/KeyedCollecting.h' and
  97.      `./objects/IndexedCollecting.h' respectively.  Examples of generic
  98.      collections are `Set' and `Bag'.  The keyed collections are
  99.      `Dictionary' and `MappedCollector'.  The classes `Array', `Queue',
  100.      `GapArray', `LinkedList', `BinaryTree', `RBTree' and `SplayTree'
  101.      are all indexed collections.
  102.  
  103.    * The string objects... [unfinished].
  104.  
  105.    * The public magnitude classes are `Time' and `Random'.  The
  106.      `Random' class works in conjunction with pseudo-random number
  107.      generators that conform to the `RandomGenerating' protocol.  The
  108.      conforming class `RNGBerkeley' provides identical behavior to the
  109.      BSD random() function.  The class `RNGAdditiveCongruential' is an
  110.      implementation of the additive congruential method.
  111.  
  112.    * Stream objects provide a consistent interface for reading and
  113.      writing bytes.  Read `./objects/Stream.h' to get the general idea.
  114.      `StdioStream' objects work with files, file descriptors, FILE
  115.      pointers and pipes to/from executables.  `MemoryStream' objects
  116.      work with memory buffers.
  117.  
  118.    * Coders provide a formatted way of writing to Streams.  After a
  119.      coder is initialized with a stream, the coder can encode/decode
  120.      Objective C objects and C types in an architecture-independent
  121.      way.  See `./objects/Coder.h' for the abstract superclass
  122.      interface; see `./objects/Coding.h' for the protocol adopted by
  123.      objects that read and write themselves using coders.  The
  124.      currently available concrete coder classes are `BinaryCoder', for
  125.      reading and writing a compact stream of illegible bytes, and
  126.      `TextCoder', for reading and writing human-readable text (which
  127.      you can also process with `perl', `awk', or whatever scripting
  128.      language you like).
  129.  
  130.      Coders and streams can be mixed and matched so that programmers can
  131.      choose the destination and the format separately.
  132.  
  133.      Neither the stream or coder class heirarchies are very mature yet.
  134.      I threw them together because I needed them for distributed
  135.      objects.
  136.  
  137.    * The distributed object support classes are `Connection', `Proxy',
  138.      `ConnectedCoder', `Port' and `SocketPort'.  This version of the
  139.      distributed objects only works with sockets.  A Mach port back-end
  140.      should be on the way.
  141.  
  142.      [NOTE: The GNU distributed object facilities have the same
  143.      ease-of-use as NeXT's; be warned, however, that they are not
  144.      compatible with each other.  They have different class
  145.      heirarchies, different instance variables, different method names,
  146.      different implementation strategies and different network message
  147.      formats.  You cannot communicate with a NeXT NXConnection using a
  148.      GNU Connection.  The GNU distributed object code does not work
  149.      with the NeXT Objective C runtime.  NXConnection creates NXProxy
  150.      objects for local objects as well as remote objects; GNU
  151.      Connection doesn't need and doesn't create proxies for local
  152.      objects.  NXProxy asks it's remote target for the method encoding
  153.      types and caches the results; GNU Proxy gets the types directly
  154.      from the local GNU "typed selector" mechanism and has no need for
  155.      querying the remote target or caching encoding types.  The NXProxy
  156.      for the remote root object always has name 0 and, once set, you
  157.      cannot change the root object of a NXConnection; the GNU Proxy for
  158.      the remote root object has a target address value just like all
  159.      other Proxy's, and you can change the root object as many times as
  160.      you like.  See the "lacking-capabilities" list below for a partial
  161.      list of things that NXConnection can do that GNU Connection
  162.      cannot.]
  163.  
  164.      To begin using distributed objects, you only need to know about
  165.      `Connection' class.  You can see the full interface in
  166.      `./objects/Connection.h'.  The long list of methods may be a little
  167.      daunting, but actually, a lot can be done with just a few key
  168.      methods:
  169.  
  170.           - (Connection*) newRegisteringAtName: (const char*)name
  171.               withRootObject: anObj;
  172.                 For registering your server object with the network.
  173.           
  174.           - (void) runConnection;
  175.                 For running the connection object returned by the above
  176.                 method, so that your server can start handling requests from
  177.                 clients.
  178.           
  179.           - (Proxy*) rootProxyAtName: (const char*)name
  180.               onHost: (const char*)host;
  181.                 For connecting to a remote server.  You get a proxy object for
  182.                 the remote server object, which, for messaging purposes, you
  183.                 can treat as if it were local.
  184.  
  185.      Here is a partial list of what the current distributed objects
  186.      system can do:
  187.           - It can pass and return all simple C types, including char*, float
  188.             and double, both by value and by reference.
  189.           - It can pass structures by value and by reference, return
  190.             structures by reference.  The structures can contain arrays.
  191.           - It obeys all the type qualifiers: oneway, in, out, inout, const.
  192.           - It can pass and return objects, either bycopy or with proxies.
  193.             An object encoded multiple times in a single message is properly
  194.             decoded on the other side.
  195.           - Proxies to remote objects are automatically created as they are
  196.             returned.  Proxies passed back where they came from are decoded
  197.             as the correct local object.
  198.           - It can wait for an incoming message and timeout after a
  199.             specified period.
  200.           - A server can handle multiple clients.
  201.           - The server will ask its delegate before making new connections.
  202.           - The server can make call-back requests of the client, and keep
  203.             it all straight even when the server has multiple clients.
  204.           - A client will automatically form a connection to another client
  205.             if an object from the other client is vended to it. (i.e. Always
  206.             make a direct connection rather than forwarding messages twice,
  207.             once into the server, from there out to the other client.)
  208.           - The server will clean up its connection to a client if the client
  209.             says goodbye (i.e. if the client connection is freed).
  210.           - When the connection is being freed it will send a invalidation
  211.             notification message to those objects that have registered for
  212.             such notification.
  213.           - Servers and clients can be on different machines of different
  214.             architectures; byte-order and all other architecture-dependent
  215.             nits are taken care of for you.  You can have SPARC, i386, m68k,
  216.             and MIPS machines all distributed-object'ing away together in
  217.             one big web of client-server connections!
  218.  
  219.      Here is a partial list of what the current distributed objects
  220.      system does *not* do:
  221.           - Run multi-threaded.
  222.           - Detect port deaths (due to remote application crash, for example)
  223.             and do something graceful.
  224.           - Send exceptions in the server back to the client.
  225.           - Send messages with vararg arguments.
  226.           - Return structures by value.
  227.           - Use Mach ports, pass Mach ports, pass Mach virtual memory.
  228.           - Send messages more reliably than UDP.  It does detect reply
  229.             timeouts and message-out-of-order conditions, but it's reaction
  230.             is simply to abort.
  231.           - Claim to be thoroughly tested.
  232.  
  233. Where else to look
  234. ==================
  235.  
  236. Examples
  237. --------
  238.  
  239.    A few simple example programs can be found in `./examples'.  Read
  240. and enjoy.  To compile them (after having compiled the library), type
  241. `make' in the `examples' directory.
  242.  
  243.    * `dictionary.m' demonstrates the basic features of the Dictionary
  244.      object.
  245.  
  246.    * `stdio-stream.m' creates a StdioStream object that points to a
  247.      file, writes to the file, then reads from the file.
  248.  
  249.    * `textcoding.m' shows how you can archive an object to a file in a
  250.      human-readable text format, and then read it back in again.  This
  251.      format is handy for editing archived objects with a text editor,
  252.      and is great when you want to modify/create an archive using a
  253.      scripting language like `perl' or `awk'.
  254.  
  255.    * `first-server.m' and `first-client.m' show the distributed object
  256.      version of "Hello, world".
  257.  
  258.    * `second-server.m' and `second-client.m' contain a more complex
  259.      demonstration of distributed objects, with multiple clients,
  260.      connection delegates, and invalidation notification.
  261.  
  262.    * `port-server.m' and `port-client.m' show a simple use of Port
  263.      objects.  Be warned, however, the interface to Port objects will
  264.      likely change in the near future.
  265.  
  266. Test Programs
  267. -------------
  268.  
  269.    Some of the programs I've used to test the library are in
  270. `./checks'.  Many of them are pretty messy, (desperately trying to
  271. tickle that late night bug), but at least they show some code that works
  272. when the library compiles correctly.  I'm looking for a volunteer to
  273. write some nicely organized test cases using `dejagnu'.  Any takers?
  274.  
  275. How can you help?
  276. =================
  277.  
  278.    * Read the projects and  questions in the `TODO' file.  If you can
  279.      volunteer for any of the projects, or if you have any useful
  280.      comments send me email!  <mccallum@gnu.ai.mit.edu>
  281.  
  282.    * Give me feedback!  Tell me what you like; tell me what you think
  283.      could be better.  Send me bug reports.
  284.  
  285.    * Donate classes.  If you write classes that fit in the libobjects
  286.      framework, I'd be happy to include them.
  287.  
  288.      Happy hacking!
  289.             Andrew McCallum
  290.             mccallum@gnu.ai.mit.edu
  291.  
  292.