Buffered general ufunc explanation
==================================

.. note::

  This was implemented already, but the notes are kept here for historical
  and explanatory purposes.

We need to optimize the section of ufunc code that handles mixed-type
and misbehaved arrays.  In particular, we need to fix it so that items
are not copied into the buffer if they don't have to be.

Right now, all data is copied into the buffers (even scalars are copied
multiple times into the buffers even if they are not going to be cast).

Some benchmarks show that this results in a significant slow-down
(factor of 4) over similar numarray code.

The approach is therefore, to loop over the largest-dimension (just like
the NO_BUFFER) portion of the code.  All arrays will either have N or
1 in this last dimension (or their would be a mismatch error). The
buffer size is B.

If N <= B (and only if needed), we copy the entire last-dimension into
the buffer as fast as possible using the single-stride information.

Also we only copy into output arrays if needed as well (other-wise the
output arrays are used directly in the ufunc code).

Call the function using the appropriate strides information from all the input
arrays.  Only set the strides to the element-size for arrays that will be copied.

If N > B, then we have to do the above operation in a loop (with an extra loop
at the end with a different buffer size).

Both of these cases are handled with the following code::

   Compute N = quotient * B + remainder.
   quotient = N / B  # integer math
   (store quotient + 1) as the number of innerloops
   remainder = N % B # integer remainder

On the inner-dimension we will have (quotient + 1) loops where
the size of the inner function is B for all but the last when the niter size is
remainder.

So, the code looks very similar to NOBUFFER_LOOP except the inner loop is
replaced with::

  for(k=0; i<quotient+1; k++) {
      if (k==quotient+1) make itersize remainder size
      copy only needed items to buffer.
      swap input buffers if needed
      cast input buffers if needed
      call function()
      cast outputs in buffers if needed
      swap outputs in buffers if needed
      copy only needed items back to output arrays.
      update all data-pointers by strides*niter
  }


Reference counting for OBJECT arrays:

If there are object arrays involved then loop->obj gets set to 1.  Then there are two cases:

1) The loop function is an object loop:

   Inputs:
	    - castbuf starts as NULL and then gets filled with new references.
	    - function gets called and doesn't alter the reference count in castbuf
	    - on the next iteration (next value of k), the casting function will
	      DECREF what is present in castbuf already and place a new object.

	    - At the end of the inner loop (for loop over k), the final new-references
	      in castbuf must be DECREF'd.  If its a scalar then a single DECREF suffices
	      Otherwise, "bufsize" DECREF's are needed (unless there was only one
	      loop, then "remainder" DECREF's are needed).

   Outputs:
        - castbuf contains a new reference as the result of the function call.
          This is converted to the type of interest, and this new reference 
          in castbuf will be DECREF'd (its reference count decreased) by
          later calls to the function. Thus, only after the innermost loop
          finishes do we need to DECREF the remaining references in castbuf.

2) The loop function is of a different type:

   Inputs:

	    - The PyObject input is copied over to buffer which receives a "borrowed"
	      reference.  This reference is then used but not altered by the cast
	      call.   Nothing needs to be done.

   Outputs:

            - The buffer[i] memory receives the PyObject input after the cast.  This is
	      a new reference which will be "stolen" as it is copied over into memory.
	      The only problem is that what is presently in memory must be DECREF'd first.
