Correct implementation of providing arrays for channel I/O

[nsoblath]

The Problem

At some point relatively recently I added a feature to allow the user to provide arrays to be used for channel I/O with the HDF5 library. I did this badly. In particular, I provided this functionality through the channel record objects, while in M3Stream the actual I/O with the HDF5 library is made via the stream record object. User access is typically through the channel record(s).

The Complication

This would be a simple fix except that there are two "cases" that are characterized by different relationships between the stream and channel records:

• Case A: channel records share memory with the stream record; memory is owned by the stream record
  • Sequential arrangement of channels w/in the stream
  • Any interface method
  • Any number of channels
• Case B: channel records and stream records have their own memory
  • Interleaved arrangement of channels w/in the stream
  • Separate interface method

  • 1 channel

The Fix

• M3Stream must be in charge of the interface for users to provide their own arrays for I/O.
• In Case B, M3Stream should provide the memory for the channel records, and it should enforce that the arrays are sequential such that it could be assigned as a single block of memory.
• The access functions in M3Stream that allow a user to provide the memory for I/O should accept a single memory block, and it is then responsible for setting that memory block either in the stream record (Case A) or for the channel records (Case B).