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.
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.