A worker thread is reading data from the given file and fills a buffer.
If the buffer is full, it waits until there is space. The thread starts
to do its job right after the [open( message.
Once we send the [start( message, the perform method simply tries to
read a block of samples from the buffer and copy it to the outlets. If
there is not enough data in the buffer, the method blocks - which is
something we definitely want to avoid! This is exactly the reason why we
need to wait a little bit between the [open( message and the [start(
message; otherwise the perform routine might have to wait for the
buffer, causing a dropout.
The second argument for [readsf~] is the size of the buffer. The default
value seems to be 262144 bytes (per channel). In single-precision Pd
that corresponds to 65536 samples, which should be more than enough. I
think this value comes from the times where everybody had slow HDDs with
unpredictable seek times; for modern SSDs it can be much smaller, but we
probably don't care about a few kilobytes.
(BTW, I have no idea why the help patch uses a buffer size of 1 MB...)
[writesf~] behaves just the otherway round. Since the perform routine is
the producer, we don't need to wait after the [open( message. But after
we send [stop(, we should to wait for the worker thread to drain the
buffer and write the data to disk before we send another [open( message.
Actually, I forgot something important:
Of course, the worker thread must also *open* the file! If the file is not yet cached by the OS, this can indeed take a few milliseconds. If you don't add some delay between "open" and "start", you might notice that you get a dropout the very first time, but not on subsequent times.
In fact, if you don't wait between "open" and "start", the perform method almost certainly blocks. However, often we don't notice because it may be "absorbed" by Pd's own ringbuffer (= "Delay" in the audio settings).
Anyway, I agree that the help needs some more clarification! (Just make sure you really understand how the object works before changing the help patch :)