D.12 Coroutines in ssh.c

Large parts of the code in ssh.c are structured using a set of macros that implement (something close to) Donald Knuth's ‘coroutines’ concept in C.

Essentially, the purpose of these macros are to arrange that a function can call crReturn() to return to its caller, and the next time it is called control will resume from just after that crReturn statement.

This means that any local (automatic) variables declared in such a function will be corrupted every time you call crReturn. If you need a variable to persist for longer than that, you must make it a field in one of the persistent state structures: either the local state structures s or st in each function, or the backend-wide structure ssh.

See https://www.chiark.greenend.org.uk/~sgtatham/coroutines.html for a more in-depth discussion of what these macros are for and how they work.