readme.txt

一个不错

  -- All global symbols start with Wy,WY,wy or wY 
     (for now the only exception is 'Ok', a const WyReply object)

  -- Function request reply: (return and throw)

     Functions report exit status either by returning WyRet or by throwing
     class of Reply family. 

     WyRet -- as return type

           Use WY_RETURN(em) to return reply with SLI. or return(Ok) to 
           indicate success.

     WyRet -- as base class of the throw type
           Function not appropriate to return WyRet should throw Reply (inherited
           from WyRet, adding no data member). For example constructor/
           destructor and operator overloads... Class Reply is defined not to
           cross the function call, which need programming supports.
           ('Exception' is a system-wise consideration. see C++ PROGRAMMING
            LANGUAGE, BJARNE STROUSTRUP, 3rd, p383)

           Any function detects inconsistent data should not return nor
           throw without considering how other functions will react
           to the condition (recover procedure could be entered), otherwise 
           go to std::terminate(). (Information can not be proved 'broken', and
           the propagation can not be free from 'noise')

           The exact class WyRet to throw is reserved to mean 'stack unwinding
           to exit'. Throwing mechanism of C++ language is regarded merely part
           of the function control flow, intent is much less relevant in this
           respect. (See [THE ANNOTATED C++ REFERENCE MANUAL, ELLIS,STROUSTRUP,
           15.1, p353-p355] [The Design and Evolution of C++, BJARNE STROUSTRUP
           , 16.6, p390] [C++ Standard 15.3.9])

     Use WY_THROW(...) to throw class with SLI
         WY_RETURN(...) to return WyRet with SLI
         WY_HERE(...) to set SLI at the location this macro appeared

     Function throw specification should indicate nothing or WyRet or the 
         derived class (e.g. Reply)

     Note: If compiler option WYLIB_CONFIG_NORSLI is defined, WyRet will not
           contain SLI.

  -- Class member rules

     Let T denote a given class of this library . The following member names 
     and associated functionalities are defined. 

     T()     Default constructor. The object thus construted is referred
             to as in default state and so the default object.

             Postcondition of throw: object does not exist

             Note: If object can mean 'no instance', or be unbound state etc.,
                   the default object is better thus designed, at least to be
                   safely destructable.

     reset(...)
             Reconstruct the object to the state as constructed.
             If reset(..) defined, there exists the argument corresponding
             constructor (reset() usually exists)

             For reset() (no argument), object return state (and Reply) is
             always default.

     ~T      Destruct and discard object

             Postcondition: object does not exist

     bool is_default() const
             return true iff object is equivalent to the default constructed 
             object (i.e a.is_default() <==> a==T(), if operator== is defined). 

     bool operator==(const T& rhs) const
             This function returns true iff *this and rhs are not
             distinguishable by using any non-private member on the same
             condition unless otherwise explicitly specified.

             All the returned objects or that may be modified by the members
             of T should have their operator==(const T& rhs) defined to prove
             the defined equivalence.

             Note: Object equivalence does not include equivalence of SLI and
                   address of its own.

     operator=(const T&)
             Assign object to the state as the copy constructor constructed.
             If this member is defined, then the copy constructor and 
             operator== are defined and x==T(x) yields true.

     swap(..)
             Exchange object state of *this and the argument indicated object.

             Take 'a.swap(b)' (commutative) for instance, the state of a is set
             to the state of b. The previous state of a becomes the state of b.
             The same applies for b 

             Note: No construct and destruct semantics involved

     Reply
             Class specific throw class inherited from WyRet.

     _..     prefix for system-specific members or candidate, or restricted

     wy_..   prefix for internal members

  -- No room should be left for lower-level implement.
     (This rule is borrowed from "The Design and Evolution of C++" 
      [BJARNE STROUSTRUP, 4.5, p120])

     Elements of the library should pass the evaluation of reduction.

+---------+  
|  Usage  |
+---------+
  This software is tested safe on my PC, and useful for the free programs, but
  not meant backward compatible. Use this library as the private part of your
  applications. In this manner, this library is relatively stable by your own.
  Examples are in ./example. For users of the previous version, see also
  UPDATE.TXT.

  1. General coding pattern (functional):

       Let f() be the example member function of a class T

    a. Traditional and common for many programs. Throw points information is
       not maintained.

       WyRet T::f(void) 
       {
         g(...);                   // g(...) may throw
         ...
         if(errors) {
           WY_RETURN(Wym_EBADF);   // Return WyRet(Wym_EBADF) with SLI here
         }
         return(Ok);               // succeed (normally no need to
                                   // retport SLI for a success
       }

       Note: No cleanup might suggest something not repeatable.
       Note: main(..) should catch(...), otherwise stack unwinding may
             be partially compiler defined (C++ Standard 15.3.9).

    b. Alternative full use of class Reply
       (closer to error report semantics, and a system-wise consideration)

       WyRet T::f(void)
       try {
         ......
         WyRet r=g(...);    // g(...) returns WyRet
         if(r!=Ok) {
           ......
           WY_HERE(r);      // Set SLI in r to say here.
           return(r);       // These two lines can be replaced by WY_RETURN(r)
         }
         return(Ok);
       }
       catch(const S::Reply& e) {  // Catch the class specific Reply
                                // Number of these catch blocks vary.
         ......
         WY_RETURN(e);          // Alternatively, return(e) could be used if the
                                // SLI refers to here would not be interested.
       }
       catch(const WyRet& e) { // Catch all missed thrown Reply object
                               // and convert to explicit WyRet(e)
         ......
         throw( WyRet(e) );    // exact class WyRet means stack unwinding to 
                               // exit
       }
       catch(...) {
         ......
         throw;                // cleanup and rethrow
       };
 
  2. Build the library. 
     .Applications may need to use compiler option "-pthread" and linker
      options "libwy.a -lpthread", probably one more "-lrt".
      This library would be statically linked, refer to GNU LGPL license.
     .All files are generated in the working directory.
     .Compiler symbols:
       WYLIB_CONFIG_THROWSPC  ... Use throw specifiction (default is empty)
       WYLIB_CONFIG_NORSLI    ... Class WyRet does not contain SLI

     $make libwy.a

  3. Build the library(libwy.a) and all other check files.

     $make all

  4. Install (This step is optional and worked on Fedora Core 3 Linux)
     Or just copy libwy.a, wy*.h, wy*.3wy to where you like.
     For example:

         #cp man/*.3wy /usr/local/share/man/man3
         #cp src/wy*.h /usr/local/include
         #cp src/libwy.a /usr/local/lib

  5. Miscellaneous

     $make clean    // Remove all files generated by 'make all'
     $./chk_all     // Run all the check files (limited and might be harmful).
                    // Check that all functions are available

  6. Function error codes may not exaust, always be defensive.

+----------+
| Feedback |
+----------+
 Feedback is welcome e.g. inappropriate text/code, bugs, coding samples
 to add into check files.
 ...