docs/advanced A document about deadlock potential with C++ statics

[tkoeppe]

Description

A detailed look at the interaction of the Python GIL and C++ static variable initializer guard mutexes, and in particular its potential for deadlocks.

Suggested changelog entry:

A new "Double locking, deadlocking, GIL" document was added. (Currently it does not appear in the readthedocs view. Help welcome.)

[tkoeppe]

@rwgk Please have a look.

[rwgk]

Awesome, thanks @tkoeppe!

Formatting of the tables doesn't work in my view (Files Changes -> ... -> View file).

Before trying to fix up the .md format to make the GitHub renderer happy, let's ask @henryiii: Is it OK to keep this as an .md file? Or are there strong reasons to convert to .rst?

[tkoeppe]

@rwgk Yes, I saw about the tables -- is there any alternative, supported table syntax? (But indeed, let's first see about RST.)

[henryiii]

I'd love to have more .md, and I'll be moving the changelog to md in the future.

[henryiii]

|     | T1                  | T2                  |
|-----|---------------------|---------------------|
| 1   | `mu1.lock()`{.good} | `mu2.lock()`{.good} |
| 2   | `mu2.lock()`{.bad}  | `mu1.lock()`{.bad}  |
| 3   | `/* work */`        | `/* work */`        |
| 4   | `mu2.unlock()`      | `mu1.unlock()`      |
| 5   | `mu1.unlock()`      | `mu2.unlock()`      |

	T1	T2
1	mu1.lock(){.good}	mu2.lock(){.good}
2	mu2.lock(){.bad}	mu1.lock(){.bad}
3	/* work */	/* work */
4	mu2.unlock()	mu1.unlock()
5	mu1.unlock()	mu2.unlock()

[tkoeppe]

Thanks! Will apply.

Any suggesions on how we can style "good"/"bad" examples (as green/red)?

[tkoeppe]

(Also, while I'm sending individual commits, probably best to squash when merging.)

[rwgk]

More work for LATER (I'm giving up after spending about an hour in vain):

• [TOC], {.good} and .{bad} don't render as hoped,

• the cross-references are not clickable, and

• the new doc isn't included in the readthedocs side panel.

But most importantly, the content is complete and highly informative.

[tkoeppe]

We can get rid of {.good} etc. Those are meant to style the code (in red/green), but it's not necessary.

[rwgk]

We can get rid of {.good} etc. Those are meant to style the code (in red/green), but it's not necessary.

I find them useful when reading the doc, although it doesn't look fancy.