Merge pull request #77 from sorenhein/master

Cumulative master update for v2.9.0 beta

Author: sorenhein

.gitignore

@@ -1,6 +1,7 @@
 !.gitignore
 *.o
 *.a
+*.so
 *.dll
 *.obj
 *.def
@@ -13,3 +14,7 @@ test/itest
 *.exe
 *.swp
 *.bak
+
+*.exp
+*.lib
+*.res

ChangeLog

@@ -1,3 +1,48 @@
+Release Notes DDS 2.9.0 beta
+----------------------------
+Included code for a number of multi-threading systems:
+- Windows API (was already there)
+- OpenMP (was already there)
+- GCD (new, intended for Mac, not really tested)
+- Boost (new, works on many systems, but you may have to install it)
+- STL (new, should work on most systems with a modern compiler)
+- TBB (new, not so broadly available, but portable in principle)
+- STLIMPL (new, experimental)
+- PPLIMPL (new, experimental)
+
+Tested combinations include:
+- Visual C++ with Windows API, OpenMP, Boost, STL
+- Cygwin g++ with Windows API, OpenMP, Boost, STL
+- mingw g++ with OpenMP, Boost, STL
+- Linux g++ with OpenMP, Boost, STL
+- MacOS clang with GCD, Boost, STL (static and shared library)
+- MacOS GNU g++ with OpenMP, Boost, STL
+
+The number of threads is now unlimited in principle, although the
+DLL will not let you go beyond the number of processor cores.
+
+Enabled the transposition-table code for both the large and the small
+versions in the same DLL.  Therefore there is only a single DLL
+distributed now for both.  The SMALL_MEMORY compile switch is gone.
+
+Enabled the DLL to pick the best combination of large and small
+transposition tables for a given resource set-up consisting of
+available memory and number of threads.  Yes, the DLL can choose to
+run 4 large and 2 small threads, for example.
+
+Expanded the DDSInfo systemString (which now needs 1024 chars as 
+stated in the new dll.h).
+
+MAXNOOFTABLES was increased from 32 to 40.
+
+Fixed a reliance that char == signed char (not the case on Android,
+which caused a bug).
+
+Dealt with the reported issues on the GitHub issues list.
+
+Lots of clean-up of internal code.  The code also looks more like C++.
+
+
 Release Notes DDS 2.8.4
 -----------------------
 Added a lower-memory DLL version with a compile flag.  This is about

INSTALL

@@ -7,7 +7,7 @@ know what you're doing and you'll figure it out :-).
 
 The first step is to compile the library.
 
-If you have trouble, read the Makefile.  They all have the compiler
+If you have trouble, read the Makefiles.  They all have the compiler
 warning levels set rather high, and they are set to fail even on
 warnings.  You can turn this off.  The Visual C++ version also
 requires a couple of tools that you may not have, but this too is
@@ -24,14 +24,14 @@ Generally speaking:
   the Makefile, then modify the Makefile.
 
 Once you've tested the source, you'll need the library file, the
-dll.h include from the include directory, and possibly other files
+dll.h include file from the include directory, and possibly other files
 such as dll.lib, depending on the exact system.  You don't need
 include/portab.h, although you're welcome to use it.  The library
 files needed are:
 
 Microsoft Visual C++: dds.dll, dds.lib
 mingw and cygwin: dds.dll, dds.def
-Mac and linux: libdds.a
+Mac and linux: libdds.a or libdds.so depending on compilation
 
 
 General instructions
@@ -41,88 +41,139 @@ General instructions
 
 2. Copy the right Makefile_... from the Makefiles sub-directory
 to the src directory and call it Makefile, see below. (Or use make -f)
+So for example "cp Makefiles/Makefile_Visual Makefile".
+See "System-specific data" below.
 
-3. If your compiler does not have the name assumed in the Makefile
-(see below), modify the Makefile.
+3. Check the configuration section and make any changes you need.
+- Section (1) has to do with paths for certain multi-threading systems
+  which you may or may not want/have.  If you set a certain compiler
+  flag, it is your own responsibility that you have the corresponding
+  threading system available -- otherwise the code will not compile.
+- Section (2) sets the threading systems with which you want to compile 
+  the DLL.  Note that you can have as many as you like (see below).  
+- Section (3) has to do with certain debugging flags etc. which you 
+  normally shouldn't set.
 
-4. If you don't have the "windres" and "cvtres" programs,
-then you can also manage without.  These are just used for
-getting version information into the DLL.  Delete the corresponding
-lines.
+3. Check the "Often OK" section, in particular the name of the
+compiler you want to use.
 
-5. If you want OpenMP rather than Windows multi-threading for
-some reason, find the right place in the Makefile and uncomment
-one line and comment the other.
+4. If you're on Windows and you don't have the "windres" and 
+"cvtres" programs, then you can also manage without.  These are 
+just used for getting version information into the DLL.  Delete 
+the corresponding lines.
 
-6. make clean (not necessary if you're starting clean).
+6. "make clean" (not necessary if you're starting clean).
 
-7. make depend (ditto).
+7. There is a "make depend" target, but DO NOT USE IT.  The Makefile
+is set up to read the dependencies from Makefiles/depends_*.txt.
 
-8. make (produces dds.dll on Windows, libdds.a on Linux and Mac).
+8. "make" (produces dds.dll on Windows, libdds.a or libdds.so on 
+Linux and Mac).
 
-9. make install (if you want to run tests; this is only a
-local install to ../lib, not a system-wide one).
+9. "make install" (if you want to run tests; this is only a
+local install to ../test and ../examples, not a system-wide one).
 
 
 System-specific data
 ====================
 
-Microsoft Visual C++ (Unix-like, so Cygwin and mingw)
+Microsoft Visual C++
 --------------------
 Makefile: Makefile_Visual
 Compiler: cl
 
+If you don't have a Cygwin-like set-up with access to commands
+such as "cp", see the last lines of that Makefile.
 
-Microsoft Visual C++ (Windows-like, so no "mV", different "make")
---------------------
-Makefile: Makefile_Visual_Windows
-Compiler: cl
 
-
-Mingw
------
+Windows Mingw
+-------------
 Makefile: Makefile_mingw
-Compiler: i686-w64-mingw32-g++
-
-32-bit and 64-bit variants for the tdc compiler are available.
+Compiler: g++
 
 
-Cygwin
-------
+Windows Cygwin
+--------------
 Makefile: Makefile_cygwin
 Compiler: g++
 
 
 Linux (static library .a)
-=====
-Makefile: Makefile_linux
+-----
+Makefile: Makefile_linux_static
 Compiler: g++
 
 
-Linux (dynamic library .ld)
-=====
+Linux (dynamic library .so)
+-----
 Makefile: Makefile_linux_shared
 Compiler: g++
 
 
-Apple
-=====
-Makefile: Makefile_Mac_clang (for clang compiler, single-threaded)
+MacOS clang (static library .a)
+-----
+Makefile: Makefile_Mac_clang_static
 Compiler: g++
-Supports both OpenMP and GDD multi-threading.
 
-Makefile: Makefile_Mac_gcc (for GNU g++ compiler, multi-threaded)
-Makefile: Makefile_Mac_shared (for GNU g++ compiler, multi-threaded)
+
+MacOS clang (shared library .a)
+-----
+Makefile: Makefile_Mac_clang_static
+Compiler: g++
+
+
+MacOS GNU g++ (static library .a)
+-----
+Makefile: Makefile_Mac_clang_static
+Compiler: gcc-4.9
+
+
+MacOS GNU g++ (shared library .a)
+-----
+Makefile: Makefile_Mac_clang_static
+Compiler: gcc-4.9
+
+
+Multi-threading
+===============
+
+As of v2.9.0 this works differently.  It is possible to have
+multiple threading systems in the same library.  There is a new
+DLL function called SetThreading() to select the one you want,
+in case there is more than one.  If the DLL is compiled only
+single-threaded, that is what you'll get.  If there are multiple
+options, the DLL will default to the multi-threaded one with the
+lowest number (among those compiled in, of course).  The numbers
+can be found in ../include/dll.h.
+
+It is NOT recommended to use STLIMPL and PPLIMPL as they are today.
+You cannot control the number of threads that they will want, nor
+the memory that they will consume.  But maybe some day...
+
+The others are very equivalent in terms of speed, but you might as
+well use STL if you have it, as this is probably the most portable.
+
+If you don't have a C++17 compiler, you will not get STLIMPL or
+PPLIMPL.
+
+The *IMPL versions let the system handle threads autonomously
+(up to the number of threads set by the user), whereas the others 
+are handled by DDS internally.  The *IMPL version are similar in
+speed, except if there is some near-duplication in the input hands
+(say, instances of the same distribution played in the same 
+denomination from different side).  The non-IMPL version handle
+this more efficiently.
 
 
 Testing
 =======
 
 The step "make install" above should have put the library file
-in ../lib.
+in ../test.
 
 test
 ----
+In the test directory you can compile the dtest program.
 This program tests five main modes of DDS:
 
 * solve, the solution of a hand for a given declarer and strain.
@@ -135,9 +186,11 @@ The program can use a number of pre-defined input files in the
 ../hands directory.
 
 To compile the program, you follow the same steps as for the library,
-except that you don't do a "make install".
+except that you don't do a "make install".  So you copy the right
+Makefile from Makefiles (e.g. "cp Makefiles/Makefile_Visual Makefile"),
+then type "make".
 
-You now have a program called "dtest" or "dtest.exe".  Let us 
+You should now have a program called "dtest" or "dtest.exe".  Let us 
 assume dtest.exe.  Let us also assume that your system is set up
 in such a way that your path does not include the current working
 directory.
@@ -147,19 +200,15 @@ You can invoke the program as
 ./dtest.exe
 
 which should just give a brief usage message.  If that works, then
-you can invoke the program like this:
-
-./dtest.exe file.txt mode [number of threads]
-
-file.txt has to be the name of a file EITHER in the current 
-directory OR in ../hands.  The program checks first in the current
-directory.  A good starting example is list100.txt.
+you can invoke the program like this, for example:
 
-mode has to be one of solve, calc, play, parand dealerpar.
+./dtest.exe -f ../hands/list100.txt -s solve -n 4 -m 1000
 
 The number of threads is optional.  If it is not supplied, DDS
 figures one out itself.  If it is supplied, then it is passed to
-SetMaxThreads().
+SetMaxThreads().  You can also use SetResources() instead of
+SetMaxThreads() to set the memory consumption as well.  If you use
+SetResources(), there is no need to use SetMaxThreads().
 
 Generally speaking, the test program first shows some information
 about how it was compiled.  Then it shows some ongoing timing
@@ -179,7 +228,7 @@ minimally to support a multi-threaded DLL.  However, it doesn't
 use the full capabilities of DDS, as it was written at a time when
 functions such as CalcAllTables and SolveAllBoards were not yet
 available.  Therefore it is rather slow, but it does have a nice
-hand generator built in.
+hand generator built in.  It has not been updated since v2.8.4.
 
 
 examples

README.md

@@ -6,11 +6,11 @@ DDS offers a wide range of functions, including par-score calculations.
 
 Please refer to the [home page](http://privat.bahnhof.se/wb758135) for details.
 
-The current version is DDS 2.8.4 released in March 2016 and licensed under the Apache 2.0 license in the LICENSE FILE.
+The current version is DDS 2.9.0 beta, released in May 2018 and licensed under the Apache 2.0 license in the LICENSE FILE.
 
 Release notes are in the ChangeLog file.
 
-(c) Bo Haglund 2006-2014, (c) Bo Haglund / Soren Hein 2014-2016.
+(c) Bo Haglund 2006-2014, (c) Bo Haglund / Soren Hein 2014-2018.
 
 
 Credits
@@ -27,7 +27,7 @@ Foppe Hemminga maintains DDS on ArchLinux.  He also contributed a version of the
 
 Pierre Cossard contributed the code for multi-threading on the Mac using GDS.
 
-Soren Hein made a number of contributions before becoming a co-author starting in v2.8 in 2014.
+Soren Hein made a number of contributions before becoming a co-author starting with v2.8 in 2014.
 
 
 Overview
@@ -52,7 +52,7 @@ Supported systems
 =================
 The DLLs work out of the box on Windows systems.  There is a single-threaded version for old Windows versions, and there is a multi-threaded version that works on all modern Windows systems.  This is the one you should use if in doubt.  
 
-The Windows versions use the Windows multi-threading.  The code compiles on windows (see INSTALL) with at least:
+The distributed Windows DLL uses Windows multi-threading.  The code compiles on windows (see INSTALL) with at least:
 
 * Visual C++ 2010 Express editions or later.
 * The TDM-GCC/Mingw port of g++.
@@ -73,20 +73,22 @@ The `without-multilib` is important because you won't get OpenMP otherwise, and
 
 Thanks for Pierre Cossard's contribution, the Mac port now also supports GCD multi-threading with LLVM.
 
+There's an example .Net wrapper on https://github.com/anorsich/dds.net (not supported by us).
+
 Usage
 =====
 
-DDS tries to figure out the available number of cores and the available memory.  Based on this, DDS calculates a reasonable number of threads to use.  The user can override this by calling the `SetMaxThreads()` function.  In principle SetMaxThreads can be called multiple times, but there is overhead associated with this, so only call it at the beginning of your program unless you really want to change the number of threads dynamically.
+DDS tries to figure out the available number of cores and the available memory.  Based on this, DDS calculates a reasonable number of threads to use.  The user can override this by calling the `SetMaxThreads()` or the `SetResources()` function.  In principle these functions can be called multiple times, but there is overhead associated with this, so only call it at the beginning of your program unless you really want to change the number of threads dynamically.
 
 DDS on Windows calls SetMaxThreads itself when it is attached to a process, so you don't have to.  On Unix-like systems we use an equivalent mechanism, but we have had a report that this does not always happen in the right order of things, so you may want to call SetMaxThreads explicitly.
 
 Docs
 ====
-The DDS library interface is very well documented. You find the docs, including a Markdown version which you can read online, in the /doc folder.
+The DDS library interface is documented. You find the docs, including a Markdown version which you can read online, in the /doc folder.  The Markdown version has not been updated since v2.8.4.
 
 Bugs
 ====
-Version 2.8.4 has no known bugs.
+Version 2.9.0 beta has no known bugs.
 
 Please report bugs to [email protected] and [email protected].
 

doc/DLL-dds_x.htm

@@ -7448,7 +7448,7 @@ <h3 style='page-break-after:avoid'><span lang=EN-US style='font-family:"Calibri"
 color:black'><o:p>&nbsp;</o:p></span></p>
 
 <p class=MsoNormal style='text-align:justify'><span lang=EN-US
-style='font-family:"Calibri",sans-serif;color:black'>CallAllTables calculates the
+style='font-family:"Calibri",sans-serif;color:black'>CalcAllTables calculates the
 double dummy values of the denomination/declarer hand combinations in </span><b
 style='mso-bidi-font-weight:normal'><span lang=EN-US style='font-size:11.0pt;
 font-family:"Courier New";color:black'>�*dealsp�</span></b><span lang=EN-US
@@ -7516,7 +7516,7 @@ <h3 style='page-break-after:avoid'><span lang=EN-US style='font-family:"Calibri"
 
 <p class=MsoNormal style='text-align:justify'><span lang=EN-US
 style='font-family:"Calibri",sans-serif;color:black'>The maximum number of DD
-tables in a CallAllTables call depends on the number of strains required, see
+tables in a CalcAllTables call depends on the number of strains required, see
 the following table:<o:p></o:p></span></p>
 
 <p class=MsoNormal style='text-align:justify'><span lang=EN-US