Clarification needed about locking requirements for a custom IOProxy::pwrite implementation

[jessey-git]

I'm creating a custom IOProxy for writing into some in-memory buffers. What's the exact requirements for locking inside the IOProxy::pwrite implementation?

On the one hand the IOProxy docs say:
This function is thread-safe against all other concurrent calls to pread() and pwrite(), but not against any other function of IOProxy.

But the existing IOVecOutput class seems to think otherwise. It takes a mutex inside its implementation but not for any of its other methods which seems to imply that pwrite could be called concurrently there. As the only callers of pwrite seem to be the write method, it's also strange that it would leave the m_pos variable un-guarded. I'm unclear on the protection requirements here.

Any guidance? Is concurrent writing happening against IOProxy's and if so, what methods require an implementation to manually guard?

[lgritz]

Any number of threads may be calling pread and pwrite, including concurrently, and that is guaranteed to be safe without the callers doing anything special. (*)

ALL other methods of IOProxy are NOT thread safe, meaning that undefined things may happen if you make any call (other than pread/pwrite calls) simultaneously with any other call (including pread/pwrite). If anything other than pread and pwrite might be called from multiple threads, it's up to the calling application to ensure (via locks, or whatever) that no two calls happen concurrently.

Expressed another way: an IOProxy requires that either (a) it is used from one thread only, or (b) if used by multiple threads, the only calls that are allowed to happen concurrently are calls to pread or pwrite.

As the only callers of pwrite seem to be the write method

No, the other presumed caller of pwrite is the user's program!

it's also strange that it would leave the m_pos variable un-guarded.

pwrite() is thread-safe, but write() is not. If the user calls write(), it's up to them to ensure that no other thread is simultaneously accessing the IOProxy in any way.

---

(*) Just as a pedantic note: although concurrent calls to pread or pwrite are considered thread-safe, it is not atomic. For example, two threads A and B doing writes to the same bytes concurrently might leave the file as if A happened and then B happened, or it might be as if B happened and then A happened, or it might be something else where they just all get jumbled up. There are no particular timing or consistency guarantees unless the simultaneous writes are to different ranges, if you see what I'm getting at.

[jessey-git]

Ah, and if the user program has no intention of ever calling pwrite on it own?

I guess the gist of the question was: Is it my responsibility as implementer of MyCustomIOProxy to make that comment true by implementing the locking myself? I looked at IOVecOutput for inspiration and didn't consider that it's also protecting against the user's program as well.

[lgritz]

If the program doesn't call pwrite on its own, then the user should view the entire IOProxy as needing to not be called concurrently by multiple threads.

Yes, it is the responsibility of the proxy author to make it true. That may or may not involve locks. For IOVecOutput, because pwrite might resize (reallocate) the vector, there must be a lock. A different kind of memory writer that writes into a pre-allocated fixed buffer that doesn't resize could implement pwrite with no locking. Similarly, IOFile::pwrite doesn't lock on Unix/Linux because it's implemented by the OS pwrite(), which is thread-safe (but on Windows, it does lock, because ultimately it's just using regular write() which is not thread-safe).

it's also protecting against the user's program as well.

Well, IOProxy internals do not spawn any threads, so it's only the user's program we're concerned about in terms of who might put us in a dangerous situation by calling two methods from different threads concurrently. (By "user", I just mean whatever is calling IOProxy methods.)

The whole thing mimics the situation for the POSIX read/write/pread/pwrite calls. The read/write are not safe to call concurrently with any other file operations, but pread/pwrite exist for the specific purpose of being stateless and therefore thread-safe versus each other (as long as two simultaneous writes aren't trying to change the same byte range, or a simultaneous read and write aren't referencing the same range).

[jessey-git]

Gotcha, I think I'll be able to drop the mutex from my implementation then.

Well, IOProxy internals do not spawn any threads, so it's only the user's program we're concerned about

Great! That pretty much sums this up. I originally assumed the lock was for an image format where concurrent writing was actually supported in some way.