Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I read through the mdbook doc for the first time and made some edits that bring it more up to date with current codebase.
A few explanatory comments here:
re tarpc: HTTP/JSON implies that a client could connect from any language or a web browser, but that is not correct. We do not use http as transport. Rather we use tarpc's serde_transport to transmit JSON. Clients must also use rust+tarpc (unless they reverse engineer tarpc::serde_transport)
re threads/tasks/g in neptune-core overview: It is incorrect nomenclature to call these threads. They have never been threads. Rather they are tokio spawned tasks running on tokio's threadpool. They may run on the same or different operating system thread from the parent task, at tokio's discretion. Unfortunately there are still some comments and variables in the code that refer to tasks as threads, which may perpetuate the misconception. When I have time I will make a commit to correct this.
re canonical ordering of locks: That concept existed in order to acquire multiple locks in a certain order to avoid deadlock, but now there is only a single RwLock, that can only ever be write-acquired by one party at a time, so no need for ordering.
re deadlocks: now that we have a single lock over globalstate it's pretty hard to deadlock. you almost have to do it intentionally. updated docs with some simple rules.