Unclear thread safety doc comments

[juntyr]

The wording of the thread safety level comments could be improved, especially when compared to the similar MPI levels. For the non-single levels, I am currently unsure what exactly the comments promise and require.

https://github.com/robertu94/libpressio/blob/master/include/pressio_compressor.h#L268-L275

• single: from my understanding, this requires either that there is only one thread (single level in MPI) or that the compressor plugin is only used from one thread (funnelled level in MPI)
• serialised: from my understanding, this requires that all uses of the compressor plugin (i.e. across all compressors) serialise their accesses, i.e. that there is a global mutex on the plugin
• multiple: from my understanding, this allows multiple threads to access the compressor plugin concurrently, but requires that each compressor is only used across threads in a serialised way, I.e. multiple compressors can exist across different threads, but each compressor on its own requires a mutex, but can be moved from one thread to the other
• there is currently no level to signal that each compressor instance can be accessed concurrently from multiple threads (and the same goes for other plugins)

[robertu94]

I believe your interpretations here are roughly correct. It is worth noting that in MPI, even with MPI_THREAD_MULTIPLE, there are some objects that inherently can race. For example, MPI_REQUEST, which tracks the completion status of an MPI_ISEND or similar non-blocking routines. You can't use the same request objects for two different, unrelated sends concurrently. The program won't crash, but it won't give you all the output you're looking for, either, because some states won't be accessible. LibPressio compressors with thread_multiple are the same way.

This sequence of commands are reminders that the output will be undefined (but valid with thread multiple) if you call them from separate threads. The program won't crash if you have the sequence with threads a and b:

1 a: x->set_options(opt1)
2 b: x->set_options(opt2)
3 a: x->compress(i,o)
4 b: x->compress(i,o)

But what options will it use? If this is the sequencing that happens, it will be opt2, but if 1 and 2 are swapped, it would be opt1.