God knows what's modified

luprex/syscpp/idalloc.hpp

@@ -1,12 +1,64 @@
-
+// The ID allocator.
+//
+// This ID allocator attempts to allocate IDs in such a way that the
+// synchronous model gets the same IDs as the master model.
+//
+// Every logged-in player maintains a "batch queue".  That's a fifo queue
+// of ID batches.  An ID batch is a contiguous range of IDs, containing
+// between 128 and 256 contiguous IDs.  The batch queue is difference
+// transmitted, to ensure that the synchronous model has the same
+// batches as the master model.
+//
+// When a player creates a thread, that thread gets an ID batch from the
+// player's batch queue.  When that thread allocates IDs,
+// it uses the batch it was allocated.  If the batch is used up, then the
+// thread falls back to using a global fallback allocator.  Such fallback IDs
+// are not likely to be predicted correctly.
+//
+// When a player creates a thread, he uses up one of his batches.  In the
+// master model, the batch queue is 'refilled' by creating a new batch.
+// In the synchronous model, the batch queue is not directly refilled,
+// but the difference transmitter effectively refills it.  It is imperative
+// that this difference transmission happen before the player's asynchronous
+// model runs out of batches, otherwise we'll get prediction failures.
+//
+// It is common that a thread will only use 0, 1, or 2 IDs.  If a thread
+// exits without using up most of its IDs, then the batch it contains is
+// still a pretty usable batch.  The master model will reclaim that batch,
+// putting it into a global salvage pool.  The salvage batches are later
+// used when refilling batch queues.
+//
+// ID ranges are assigned as follows:
+//
+//  0x0000+  : reserved for future expansion.
+//  0x0001+  : used by master model to allocate batches.
+//  0x0010+  : used by master model to allocate unpredictable IDs.
+//  0x001E+  : used by synchronous model to allocate stopgap IDs.
+//
+// The operations in this class are:
+//
+// idalloc.initmaster() - reinitialize the ID allocator in master mode.
+// idalloc.initsynch() - reinitialize the ID allocator in synchronous mode.
+// idalloc.setqueuefill() - override the default queue fill level.
+// idalloc.refill(bq) - get batches from the global pool until the batch queue is full.
+// idalloc.unqueue(bq) - push batches from the batch queue back into the global pool.
+// idalloc.preparethread(bq, co) - transfer a batch from the batch queue to the coroutine
+// idalloc.salvagethread(co) - push any batch in the dead coroutine back into the global pool
+// 
+// idalloc.allocid() - get an ID using either the current thread's pool or the global pool
 
 #ifndef IDALLOC_HPP
 #define IDALLOC_HPP
 
 #include "luastack.hpp"
 
-int idalloc_getnextid(lua_State *L);
-int idalloc_setnextid(lua_State *L);
+int idalloc_initmaster(lua_State *L);
+int idalloc_initsynch(lua_State *L);
+int idalloc_refill(lua_State *L);
+int idalloc_unqueue(lua_State *L);
+int idalloc_preparethread(lua_State *L);
+int idalloc_salvagethread(lua_State *L);
+int idalloc_allocid(lua_State *L);
 
 #endif // IDALLOC_HPP