Network API Docs should tell people to use correct threads

[frqnny]

To quote from quoteall,

I have something to say about the networking API's documentation. The method registerGlobalReceiver 's doc should explicitly say that the handler is invoked on networking thread which should not manipulate the server world directly. (Although the doc of PlayChannelHandler mentions that, it's not enough, this is a very important information and should be said many times). Many mods manipulate the server entities in networking thread which is unsafe (and Immersive Portals will check that and crash). Recently as far as I know Dual Wielding and AdventureZ have these issues.

We should tell people to use server#execute and client#execute when necessary.

[qouteall]

A good implementation should read the data from the buffer in the networking thread and then manipulate the world in client or server thread.

[Sollace]

I agree. This is also a very common mistake, that I've seen modders make dating back years. i.e. CodeChicken's mob dismemberment mod made this mistake and the result was that dismembering large numbers of entities could cause a crash due to concurrent modification exceptions.

It's the exact same error that I encountered in the exact same way when spawning large numbers of items until I realised it was because everything server-side was being done on the networking thread. :'D

Also to add to that, errors on the network thread can be extremely hard to debug, as they sometimes may not even get logged, rather being silently consumed by the networking handler, so yet another reason to always use client.execute or server.execute

[Technici4n]

Fixed by introducing the packet-object API: #2820.