
This file tries to establish rationale of the decision basis of the library
interface. This file is published partly for correction.

Changes of library interface resulting from contents herein may lead to 
dramatical impact on application source using this library (the library is
worth the use anyway)

 Note: Phrases in quite several places may be indifferent to the author.
       And, information in this file may have outdated. (develop on demand, 
       learn on demand, as programmers usually do)

+------------------------------------------+
| Function Reply (previously Error Report) |
+------------------------------------------+
 Considering codes being reused as a function (with respect to as macro), the 
 exit points (indicating different condition, instead of the intended
 information) of that function are traditionally simplified to one by encoding 
 it into a replied object (C++ adds a throwing channel for the function to
 exit) Caller function is thus inborn with the decoding task recovering the
 exit point information.

 There are two choices considered. Drawback of each (way of reply):

 a) by return (with respect to by throw)
    1. Idling the dedicated throwing channel.
    2. Replies are implicitly non-exaustive. Undocumented or future added 
       report is more easier to be ignored.
       Lack ability to 'catch' returned reply by static type (not yet clear the
       use, but for the comparsion with the throw channel).
    3. Not appropriate for constructor and operator members, and a bit
       redundant in programming.

 b) by throw
    1. No reliable mechanism for the replied(error) semantics from diverge.

       From the throw mechanism definition, any throws will reappear to the 
       caller as if the call point is replaced by the throw there, if no 
       handler catches it, the process (stack unwinding) continues. Thus, a 
       function call such as f() can be explicitly (in effect) replaced by
       the keyword throw of any of the underlying function which had thrown.
       (the throw point is decoded, and reappears as if the call point is the
       throw point). So the context, or semantics of the throw point propagated
       to the catch handler is basically unknown.

       Take for instance, a function call f() can initiate various sort of
       throws, invalid_argument, domain_error, overflow_error, etc... Except
       the context is irrelevant, to resolve the throw for a succeeful function,
       the handler can retry at least someway relying on the convention that
       function either succeeds or fails with 'trival effect' (note that 
       semantics of the caught object now becomes a surplus in this resolution
       at this point). Such tries in the responsible caller is, for most
       failure replies, harder to report a faithful success at the end without
       changing or modifying the functionality... So the result would normally
       still be a throw someway, only more vague or more of a general failure
       nature. This condition recurres.

       Information from the net throw channel mechanism makes the semantics
       vague, more so the deeper of the call chain. Hence the divergent
       characteristic is concluded: function gets less and less functional
       more quickly.

    2. In the stack unwinding, another throw can occur, particularily it is
       initiated from an asyncronous event, which normally leads to
       std::terminate.

 For this library, passing the resultant status (errno mostly) of an underlying
 C-function call seems inevitable. Considerations are such as interchangibility
 with the type to throw, speed/size (no more than a single data item in the
 return type), completeness in reducing future maintenance work (the return/
 throw mechanism is seen can spread throughout and between user programs).

 This library inclines to report function reply via the return channel if
 not too bad (source checking utility could probably help spot the ignorance)
 If both the throw and return versions were to be in this library, the return
 version is prefered in priority, since it can be wrapped to simulate the throw
 version.

 Memory exaustion is considered inevitable (beside the hidden stack), hence
 constructors will throw Reply(Wym_ENOMEM) if memory allocation is/would be
 involved (constructors is recommended to avoid failure).

 Class Reply is a wrapper of the return class WyRet (same size), is intended
 the means to identify the throw point (function return status) of the
 function being called, so as to mimic semantics that would be derived from
 the return channel.
 The Reply mechanism (to catch and identify the throw point before too much 
 uncertainty gets involved in the stack unwinding) requires programming support.
 If application is not sure the mechanism is maintained, the other option 
 is reserved, i.e. catch WyRet, cleanup local changes and rethrow as usual and
 do not interpret throw point of Reply.

 Throw specification documented in this library is primarily to make nothrow 
 functions possible(destructors, cleanup codes and catch handlers want this).
 The throw specification in manpages is shown as _throw_ to mean that the real
 implement is empty (if compiled with WYLIB_CONFIG_THROWSPC defined, throw
 specification is implemented).

 In the default construct, throw specification is not used is beacuse comparing
 with a function that tries to simulate the specification effects, more
 drawbacks than documentation benefits are felt:

   .Function typedef/signature problem restricts popular use.
   .The recurrence of runtime overhead are hardly felt worthy in functions
    that just return a single data item or are simple wrappers of a function
    or functions known nothrow.
   .Functions with throw spcification do not therefore encourage caller
    functions also to use throw specification. For caller functions are
    nonetheless easier to have throwing guarantee from the underlying codes
    that may initiate the stack unwind by whatever reason.

  Note: Development of this library is tending minimizing the use of the throw
        specification macro (_throw_) if a C-library function is used.
  Note: Members of class WyRet are guananteed nothrow without throw
        specification.

 Comment: Application might feel checking the result of every function is
          tedious, but experience is that programming task about 2000 lines
          would have begun exhibiting benefits of both speed and quality, even
          it is expected to live only for several executions (especially with
          the support of source location information). A point is that widely
          reusable codes have to handle those 'branches', no absolute answer to
          the how part. Decoding of the exit point normally means to branch to
          a more expansive implement for a successful function request.

  Source location information SLI can be viewed as the branch point information
  for human to decode. Use of SLI reduces significant development and
  maintenance efforts. This is the author's experience, however. Compiler symbol
  WYLIB_CONFIG_NORSLI is provided to disable SLI support. Few reasons found of
  doing this but for that users (I am one) always like to use things exactly
  needed, zero overhead, no imposed burdon, requirements... Another reason is
  that the provision is handy.

+-----------------------------------------------------+
| General interface about object/information coupling |
+-----------------------------------------------------+
 For efficiency, information input/output in many cases may be attributed as
 'incomplete' by using reference/pointer if address is not really meant (with 
 respect to i/o by value), in that information does not really pass to the 
 destination but an address. This library uses reference in place of value in 
 the way as commonly practiced (which is also normally better and required if
 it is copy constructors' source).

 Implicication may be tricky, e.g. the self-operate-self pattern, as frequently 
 observed in t.reset(t), is usually handled in silence as if it were passed by 
 value. But it may be said that one more piece of information (the easier 
 abused one) is implicitly introduced to the function domain.
 In some instances, the constness guarantee of the argument may not be true, the
 basic is when two objects overlap (exactly the ability of pointer/reference,
 and several of them may be in forms not immediately recognizable).

+-------+
| WyStr |
+-------+
 The primary feature of WyStr is to provide flexible char buffer and to handle
 the implying trailing char(0) of a C style string.
 
 WyStr is not the direct part of the conversion for the underlying syscalls and
 C-library, the benefits in practice is the facilitation of ::mkstemp(..), 
 ::ttyname_r(..),..,data I/O etc. reducing the need to use C-library things such
 as macro PATH_MAX,..sysconf.

+------------+
| Compromise |
+------------+
 As decision is often implicit result of compromise or even random choice from
 the distribution pattern of practical usage. This paragraph tries to establish 
 validation of such stuff, by simply listing known facts or phenomena that are
 generally applicable.

 1. Derived from traditional logic (or intuition).
    Object A, A and none-A exist at the same moment (coexist)

 2. Derived from computer mathmatics.
    Let t:N->N be a 1-1 transformation function, N is the set of natual number.
    u,v is subset of N and v=t(u). # denotes the sizeof function, then
    #(u)+#(!u) == #(v)+#(!v)

    This roughly means if set X is 'compressed' to another set, say X'. 
    then #(!X') 'increases' by the same quantity over #(!X), vice versa.
    (some form of fixed-sum, infinite+finite may be questionable, though)

    [Hint or application]
         X might even be abstract notion like an C++ object can be, as 
         experiment for instance:
         (order/chaos, as X is more in order, the opposite !X might be measured)
         (force/counter force, feature, property gain/loss in a closed system)
         (wake/sleep, efficient use evolution)
         .....

+----------------------------------------------------------+
| Sequence of acquisition incident: Object life cycle view |
+----------------------------------------------------------+
 1. Name binding
    (there might be anonymous object)
 2. Size binding
    Information to allocate memory
 3. Address binding
    Object in this stage is called in random state.
 4. Semantics binding
    Object is in responsible state of the occupied space.
    (external resource may be associated in the semantics)
 5. Reversal is the object destruct process

    Note: Class of objects whose destructor can be runtime ignored is referred
          to as discardable in this library. Often, such class has no user
          defined destructor.

----Result of the life cycle view is the basic rule of class members
 Constructor(..):
   Constructor forms are in basic the Cartesian product view of problem domain
   in tupple. Constructor brings an object in random state to responsible
   state.

 Reset(..) members:
   Reset in theroy brings an object from responsible state back to random state
   and then does whatever the argument corresponding constructor does.

   Construct/destruct/reset are implemented as composite operations of object
   initialization process of the life cycle view (and the symmetrical reverse).

 Reset() is special:
   [12.4.14] Once a destructor is invoked for an object, the object no longer
   exists; ... Because destructor can only be called legally once and the object
   is then regarded non-existant by the language, class design should allow
   state transition path that an object can always be successfully brought back
   to random state (may be destruct by discard).

   It is convenient letting reset() the bring-back function which always
   succeeds, or the front part of that bring-back sequence.
