Add comments and minor MM tweaks to qio and regexp implementations [reviewed by ]

Mostly added comments regarding the expected state of the ref count in reference
counted objects.  I verified the correct operation of reference counting within
the runtime implementation and Chapel wrappers by first making the starting
reference count zero and then adding ?_retain() and ?_release() calls as needed
in close proximity to where references were being created or destroyed.  In this
way, I was able to verify the correctness of the reference counting
implementation "by inspection".

Although easy to verify, this approach has a slight performance impact, since on
the expected execution path the creation of a new reference-counted object
entails creating the reference count initialized to zero and then immediately
incrementing it.  Per Michael's request, I restored the original behavior by
initializing the reference count to 1 and then removing redundant ?_retain()
calls and adding newly necessary ?_release() calls.  In most places, I replaced
the ?_retain() call with a comment, so the expected state of the reference count
is documented.  This can be an aid to debugging.

There were only a few places where calls to alter the reference count had to be
added:
  _qio_file_destroy() -- Added calls to qbytes_release() and qbuffer_release().
  qio_regexp_create_compile() -- Added call to DO_RETAIN().

[Tested using the standard configuration in test/io/ and test/regexp/ only.
Memleaks were logged, and compared equal to the same on TRUNK.]


DETAILS

Below are noted material changes beyond the addition of comments.  Files changed
only through the addition of comments are not mentioned.


    runtime/include/qio/qbuffer.h
Consolidated the test for an out-of-range reference count.


    runtime/include/qio/qio.h
Code segments for debugging the reference count in qio_channel_t objects are now
enabled by setting DEBUG_QIO in the environment and recompiling the runtime.

    runtime/src/qio/qio.c
Following two calls to qio_free(file), the freed file pointer is set to zero to
avoid the possibility of use-after-free or double-deletion.

Missing calls to qbytes_release() and qbuffer_release() were added to
_qio_file_destroy().


    runtime/src/qio/regexp/re2/re2-interface.cc
In qio_regexp_create_compile, the reference count is bumped before returning a
reference to the cached regexp to the user.  The cache is implemented such that
a new regexp can eject an old one from the cache.  If the ref count went to zero
at that point, then the regexp would be deleted, leaving the client of this
routine holding a dangling reference.  Therefore, bumping the reference count is
necessary.  This also places the requirement on the client code, that the regexp
be release when the client code is done with it.


    modules/standard/Regexp.chpl
It was necessary to change the signature of the assignment operator back to the
old style (without "ref" intent on the LHS argument) to get it to bind
properly.  When the "ref" intent is present, the user-defined assignment
operator is ignored and the compiler-generated one is used instead.  This
problem will be corrected in a separate patch.


    modules/standard/IO.chpl
Corrected a small think-o in the signature for
channel.match_regexp_if_needed().  The r:_channel_regexp_info must be passed by
ref, so it can be updated in the body of the routine.



git-svn-id: http://svn.code.sf.net/p/chapel/code/trunk@22135 3a8e244f-b0f2-452b-bcba-4c88e055c3ca