Document our de-facto thread-safety policy

[Zalathar]

As pointed out in #2717, we don't appear to have any documented policy on whether or not Hypothesis is thread-safe.

Actually making Hypothesis more thread-safe would be a bunch of work and out-of-scope for this issue, so here I'm mostly focused on being more transparent about the current situation.

I see three main scenarios worth documenting:

• Running in multiple processes (e.g. under pytest -nauto)

  • I don't know if we have explicit tests for this, but our own test suite routinely runs in multiple processes, so hopefully we should notice any problems pretty quickly.
  • This mostly involves making sure that our file-backed database can't tread on its own toes too badly.

• Running separate tests in multiple threads

  • Hypothesis isn't explicitly designed or tested for this, so it's not formally “supported“, but anecdotally it does mostly work and we would like it to keep working.
  • This mostly involves being careful about global state, shared caches, and cached strategies.
  • We accept bug reports and reasonable patches.

• Using multiple threads within a single test

  • Hypothesis assumes that tests are single-threaded, or do a sufficiently-good job of pretending to be single-threaded.
  • Tests that use helper threads internally should be OK, but the user must be careful to ensure that test outcomes are still deterministic.
    • Tests that change their dynamic draw behaviour based on helper-thread timing count as nondeterministic, so don't do that.
    • Deterministic stack traces might be a danger point here; I'm not sure.
  • Interacting with any Hypothesis APIs from helper threads might do weird/bad things, so don't do that.
    • This is because we rely on thread-local variables in a few places, and haven't explicitly tested/audited how they respond to cross-thread API calls.
    • Dynamic draws from st.data() are the most obvious danger, but other APIs might also be subtly affected.

Does this seem mostly accurate?

[Zac-HD]

Yep, looks good to me - thanks for writing it up @Zalathar!

I'd note under "Running separate tests in multiple threads" that running a single test in multiple threads has all these problems but more so - it might work for simple examples, but I would expect this to be pretty fragile.