1 files changed, 65 insertions, 0 deletions
diff --git a/README.mig-alloc-reform b/README.mig-alloc-reform
new file mode 100644
index 0000000..139af2e
--- /dev/null
+++ b/README.mig-alloc-reform
@@ -0,0 +1,65 @@
+What is mig-alloc-reform?
+  1. A massive simplification of the memory management in Tcl core.
+     a. removal of the Tcl stack, each BC allocates its own stacklet
+     b. TclStackAlloc is gone, replaced with ckalloc; goodbye to sometimes
+        hard sync problems
+     c. removal of the allocCache slot in struct Interp
+     d. retirement of the (unused) Tcl allocator USE_TCLALLOC; replacement
+        with a single-thread special case of zippy
+     e. unify all allocator options in a single file tclAlloc.c
+     d. exploit fast TSD via __thread where available (autoconferry still
+        missing, enable by hand with -DHAVE_FAST_TSD)
+     f. small improvement in zippy's memory usage: try to split blocks in
+        the shared cache before allocating new ones from the system
+
+  2. New allocator options
+     a. purify build (but stop using them, see below). This is suitable to
+        use with a preloaded malloc replacement
+     b. (~NEW) native build: call to sys malloc, but maintain zippy's
+        Tcl_Obj caches (per thread, if threads enabled). Can be switched to
+        run as a purify build via an env var at startup. This is suitable to
+        use with a preloaded malloc replacement. The threaded variant is new. 
+     c. zippy build
+     d. (NEW) multi build: this is a build that can function as any of the
+        other three. Per default it runs as zippy, but can be switched to
+        native or purify via an env var at startup. May or may not be used
+        for deployment, but it will definitely be very useful for
+        development: no need to recompile in order to valgrind, just set an
+        env var!
+     
+ How do you use it? Options are:
+   1. Don't pay any attention to it, build as always. You will get the same
+      allocator as before
+   2. Select the build you want with compiler flags
+        -DTCL_ALLOCATOR=(aNATIVE|aPURIFY|aZIPPY|aMULTI)
+   3. Select behaviour at startup: native can be switched to purify, multi
+      can be switched to any of the others. Define the env var
+      TCL_ALLOCATOR when starting up and you're good to go
+
+
+** PERFORMANCE NOTES **
+   * not measured, but: purify, native and zippy builds should be just as
+     fast as before. The obj-alloc macros have been removed while
+     developing. It is not certain that they provide a speedup, this will
+     be measured and acted accordingly 
+   * multi build should be a only a tad slower, may even be suitable as
+     default build on all platforms 
+
+
+** TO DO LIST **
+   * DEFINITELY
+     - test like crazy
+     - timings: versus older version (in unthreaded, fast-tsd and slow-tsd
+       builds). Determine if the obj-alloc macros should be reenabled
+     - autoconferry to auto-detect HAVE_FAST_TSD
+     - autoconferry to choose allocator flags? Keep USE_THREAD_ALLOC and
+       USE_TCLALLOC for back compat with external build scripts only (and
+       set them too!), but set also the new variants  
+          TCL_ALLOCATOR=(aNATIVE|aPURIFY|aZIPPY|aMULTI)
+     - Makefile.in and autoconferry changes in windows, mac
+     - choose allocators from the command line instead of env vars?
+     - verify interaction with memdebug (should be 'none', but ...)
+
+   * MAYBE
+     - build zippy as malloc-replacement, compile always aNATIVE and
+       preload alternatives