Buffering API...

[Ryan C. Gordon]

PhysicsFS, in the latest CVS, now has the ability to buffer i/o to memory.

To use it:

  PHYSFS_file *f = PHYSFS_openRead("/my/dir/myfile.ext");
  if (f != NULL)
  {
      int rc = PHYSFS_setBuffer(f, 2048);
      // if rc != 0, you've got a 2k buffer for that file now.
  }

  Once a file is buffered, the next call to PHYSFS_read() will fill the
buffer, and will take data from there until it needs refilling.

If you buffer a file opened for write/append, all calls to PHYSFS_write()
will fill that buffer until it's full, and then flush it to begin
refilling. If you want to explicitly flush it, you call:

    PHYSFS_flush(f);

AND CHECK THE RETURN VALUE! Since we're buffering, PHYSFS_write() could
succeed but the flush (or close, which implicitly flushes) could fail.

If you want to unbuffer a file, call PHYSFS_setBuffer() with a zero. Files
are unbuffered by default (assuming the OS allows this).


seek, eof, tell, etc all take the buffer into account and should work
transparently.

There are commands in test_physfs for testing the buffering code:

   "setbuffer x" will set a buffer on future "cat" and "append" and
"write" commands and "stressbuffer x" will run a stress test (please set
the writedir and searchpath to "." first).

This is only lightly tested, but it seems fairly functional. Please pound
on it. I'll package up physfs 0.1.8 in a day or two.

--ryan.