6.05 release

BUILDOPTIONS.txt

@@ -0,0 +1,260 @@
+muscled should compile fine with nothing more than a "cd muscle/server ; make" 
+but if you feel like hacking around, here is a list of some 
+compile-time constants that you can define in the CXXFLAGS variable
+of your Makefile to alter muscle's behaviour:
+
+-DMUSCLE_ENABLE_SSL
+   Set this to enable built-in support for SSL connections via OpenSSL.
+   (e.g. ReflectServer::SetSSLPrivateKey())
+
+-DMUSCLE_USE_CPLUSPLUS11
+   Set this to enable C++11-specific features such as move-constructors.
+
+-DMUSCLE_AVOID_IPV6
+   Set this to indicate that Muscle should be compiled without IPv6
+   support.  The main difference with this flag is that muscle_ip_address
+   will be defined a typedef'd alias for a uint32 (rather than a C++ class
+   that holds 128 bits of data).
+
+-DMUSCLE_SINGLE_THREAD_ONLY 
+   Makes the Mutex class's methods compile down to no-ops.  Specify this if 
+   you are able to guarantee that your program will never access MUSCLE
+   code from more than one thread.
+
+-DMUSCLE_USE_EPOLL
+   Causes the SocketMultiplexer class to use the epoll() Linux system
+   call instead of select().  This method is less portable, but 
+   avoids the FD_SETSIZE limitation that select() introduces.
+   Note that this flag is mutually exclusive with -DMUSCLE_USE_KQUEUE and
+   -DMUSCLE_USE_POLL.
+
+-DMUSCLE_USE_POLL
+   Causes the SocketMultiplexer class to use the poll() system
+   call instead of select().  This method is slightly less portable, but 
+   avoids the FD_SETSIZE limitation that select() introduces.
+   Note that this flag is mutually exclusive with -DMUSCLE_USE_KQUEUE
+   and -DMUSCLE_USE_EPOLL.
+
+-DMUSCLE_USE_KQUEUE
+   Causes the SocketMultiplexer class to use the kqueue() and kevent() 
+   system calls instead of select().  This method is less portable, but
+   avoids the FD_SETSIZE limitation that select() introduces.
+   Note that this flag is mutually exclusive with -DMUSCLE_USE_POLL and
+   -DMUSCLE_USE_EPOLL.
+
+-DMUSCLE_MAX_ASYNC_CONNECT_DELAY_MICROSECONDS=(#micros)
+   If specified, MUSCLE's AddNewConnectSession() calls
+   will force an asynchronous connection to fail after this
+   many microseconds have elapsed.  If not defined, the
+   default behavior is to let the operating system determine
+   when the asynchronous connection should time out and fail.
+
+-DMUSCLE_CATCH_SIGNALS_BY_DEFAULT
+   If specified, ReflectServer will by default set up a signal 
+   handler to catch signals (e.g. Control-C), and gracefully 
+   exit its event loop when they are detected.  Without this
+   flag, MUSCLE signal-handling routines will only be set up
+   if you explicitly call SetSignalHandlingEnabled(true)
+   somewhere in your code.
+
+-DMUSCLE_USE_LIBRT
+   If specified, GetRunTime64() and Snooze64() will use librt's
+   high-resolution timing functions instead of the low-resolution
+   ones supplied by older operating systems.  Note that if you 
+   specify this flag, you should link with librt as well (-lrt).
+
+-DMUSCLE_AVOID_MULTICAST_API
+   Set this to omit the multicast API calls in NetworkUtilityFunctions.h.  
+   This might be useful to do if compiling on a platform where multicast
+   APIs aren't supported.
+
+-DMUSCLE_ENABLE_KEEPALIVE_API
+   Set this to make the TCP keepalive API calls in NetworkUtilityFunctions.h
+   available for use.  (it's disabled by default to make sure that the
+   keepalive functions won't break the build on platforms that don't 
+   support keepalive).  Note that muscled itself won't use keepalive even 
+   if this constant is specified; the functions are a convenience for 
+   other MUSCLE-based applications to use if they wish.
+
+-DMUSCLE_64_BIT_PLATFORM
+   Set this to indicate that compilation is being done on a 64-bit platform.
+   This flag will be set automatically in support/MuscleSupport.h if defines
+   indicating a known 64-bit platform are detected; if not, you can set it
+   yourself in the Makefile if necessary.
+
+-DMUSCLE_USE_LLSEEK
+   Force the FileDescriptorDataIO class to use the non-standard _llseek() command
+   when compiled under Linux.  This should be done automatically in most cases
+   where it is necessary, but you can force it also.
+
+-DMUSCLE_PREFER_QT_OVER_WIN32
+   Tell the Muscle Thread/Mutex/etc classes to prefer to use Qt Threading APIs over Win32 calls
+   when both are available.  (By default, Win32 calls are preferred when running under Windows)
+
+-DMUSCLE_ENABLE_MEMORY_PARANOIA=N 
+   Put N overwrite-guards before and after each malloc() buffer, watch them for memory corruption
+
+-DMUSCLE_NO_EXCEPTIONS 
+   Tells muscle that exceptions won't be used.
+
+-DMUSCLE_ENABLE_MEMORY_TRACKING 
+   Enables system memory usage tracking (wrappers for new and delete that allow muscled to
+   put an upper bound on the amount of memory it dynamically allocates, etc)
+
+-DMUSCLE_AVOID_ASSERTIONS 
+   makes MASSERT statements into no-ops
+
+-DMUSCLE_AVOID_SIGNAL_HANDLING
+   Disables the built-in support for catching signals and doing an orderly shutdown of
+   the ReflectServer event loop in response.
+
+-DMUSCLE_AVOID_INLINE_ASSEMBLY
+   tells muscle to use boring old C/C++ code and avoid using any clever assembly-language code
+
+-DMUSCLE_ENABLE_ZLIB_ENCODING 
+   enables support for zlib compression of Messages
+
+-DMUSCLE_TRACE_CHECKPOINTS=N 
+   enable TCHECKPOINT tracing of last N checkpoints
+
+-DMUSCLE_DISABLE_MESSAGE_FIELD_POOLS 
+   turn off Object pooling for Message field objects; helpful for debugging
+
+-DMUSCLE_MAX_OUTPUT_CHUNK=N 
+   tell muscled not to send() more than N bytes of output per call
+
+-DMUSCLE_INLINE_LOGGING 
+   turn Log(), LogTime(), etc into simple printf() passthroughs
+
+-DMUSCLE_DISABLE_LOGGING 
+   turn Log(), LogTime(), etc into no-ops
+
+-DMUSCLE_USE_MUTEXES_FOR_ATOMIC_OPERATIONS 
+   Use Mutexes to simulate atomic inc/dec operations; useful if no other method is available
+
+-DMUSCLE_MUTEX_POOL_SIZE=N
+   If -DMUSCLE_USE_MUTEXES_FOR_ATOMIC_OPERATIONS is defined, then this can be defined to set the size of the Mutex pool to use.  Defaults to 256.
+
+-DMUSCLE_POWERPC_TIMEBASE_HZ=N 
+   Use mftb/mftbu for GetRunTime64() calls.  N is the frequency at which the register is incremented
+
+-DMUSCLE_USE_PTHREADS 
+   Use pthreads for thread operations
+
+-DMUSCLE_DEFAULT_TCP_STALL_TIMEOUT=N 
+   Number of microseconds to wait for a client to read TCP data before 
+   giving up and closing his connection (defaults to 20 minutes' worth)
+
+-DMUSCLE_FD_SETSIZE=N 
+   Redefine the fd_setsize to another value (useful under Windows, where the default setsize is a measly 64)
+
+-DMUSCLE_AVOID_NEWNOTHROW 
+   Turns newnothrow into a synonym for "new", instead of "new (nothrow)"
+
+-DMUSCLE_AVOID_FORKPTY 
+   Tells the ChildProcessDataIO class not to compile in calls to forkpty(); instead it will use fork() only
+
+-DMUSCLE_HASHTABLE_DEFAULT_CAPACITY=X 
+   Number of value slots to initially pre-allocate in a Hashtable, by default (defaults to 7)
+   Note that the pre-allocation is done the first time an object is Put() into the Hashtable.
+   A new, empty Hashtable will have no pre-allocated slots.
+
+-DSMALL_QUEUE_SIZE=N
+   Number of value slots to initially pre-allocate in a Queue, by default.  (defaults to 3)
+
+-DSMALL_MUSCLE_STRING_LENGTH=N 
+   strings <= this length will be stored inline in the String object to avoid a malloc()... default is 7
+
+-DMUSCLE_USE_QUERYPERFORMANCECOUNTER
+   Tells MUSCLE's GetRunTime64() to use the higher-resolution 
+   QueryPerformanceCounter() API instead of timeGetTime() when running under Windows.
+   Specifying this flag increases GetRunTime64()'s accuracy, but QueryPerformanceCounter()
+   is known not to work on some hardware.
+
+-DMUSCLE_INCLUDE_SOURCE_LOCATION_IN_LOGTIME
+   Compiles MUSCLE's and LogTime() function as a macro that includes the
+   source code location in the call.  By enabling this it is possible to include
+   the source of a message with the messge itself, should your code choose to do so.
+
+-DMUSCLE_WARN_ABOUT_LOUSY_HASH_FUNCTIONS=200
+   If defined, the Hashtable::EnsureSize() method will do some paranoia
+   checking every time it resizes the Hashtable, to see if the Hashtable's
+   average lookup-count (as calculated by CountAverageLookupComparisons())
+   is greater than 2.00f (or whatever the preprocessor-define's value is,
+   divided by 100).  If it is, a log message, debug info, and a stack trace
+   will be printed.  Only enable this compiler flag when doing debugging/
+   development/optimization (i.e. when you want to check to see if you 
+   have any hash functions that aren't performing well), since it will
+   significantly slow down your program when it is enabled.
+
+-DMUSCLE_ENABLE_DEADLOCK_FINDER
+   If specified, calls to Mutex::Lock() and Mutex::Unlock() will
+   print trace information to stdout that can later be used by
+   the deadlockfinder program (in the tests folder) to detect
+   potential deadlocks in the code caused by inconsistent lock
+   acquisition ordering.
+
+-DMUSCLE_DEFAULT_RUNTIME_DISABLE_DEADLOCK_FINDER
+   If this is specified in addition to -DMUSCLE_ENABLE_DEADLOCK_FINDER,
+   then deadlock-detection will be compiled into the code but the
+   printouts will be disabled by default.  To enable them at runtime,
+   set the global variable _enableDeadlockFinderPrints to true.
+
+-DMUSCLE_POOL_SLAB_SIZE
+   This can be set to a number indicating the number of bytes that should be
+   allocated in each "slab" of data malloc()'d by the ObjectPool class.  If left
+   unset, slabs of approximately 8 kilobytes will be used.  Large slabs mean
+   fewer memory allocations, but potentially more memory wasted if all the objects
+   in the slabs aren't needed.  This value should be specified in bytes.
+
+-DMUSCLE_AVOID_BITSTUFFING
+   If set, this flag will cause the RefCount and ByteBuffer classes
+   to use a separate boolean state value, rather than stuffing that bit
+   into its held pointer.  This flag might be necessary on systems
+   that don't word-align their object pointers (if such systems exist)
+
+-DMUSCLE_AVOID_CHECK_THREAD_STACK_USAGE
+   If set, calls to the CHECK_THREAD_STACK_USAGE macro will be
+   converted into no-ops.
+
+-DMUSCLE_AVOID_OBJECT_COUNTING
+   If defined, the CountedObject<> class will compile down to a no-op.
+
+-DMUSCLE_AVOID_THREAD_LOCAL_STORAGE
+   If defined, the MUSCLE code will try to avoid using the ThreadLocalStorage
+   class where possible (in particular, it will use Mutexes inside the
+   ZLibUtilityFunctions.cpp file rather than ThreadLocalStorage objects --
+   this might be useful on systems where ThreadLocalStorage isn't implemented)
+
+-DMUSCLE_AVOID_MINIMIZED_HASHTABLES
+   If defined, the MUSCLE Hashtable class will not used variable-sized
+   indexing in its HashtableEntries.  Variable-sized indexing saves memory
+   when tables have less than 65,535 slots in them, but increases the
+   number of "if" statesments in common Hashtable codepaths.  Whether or
+   not it increases or decreases performance will depend on the architecture
+   of the host computer (e.g. on cache size, CPU speed, etc).
+
+-DMUSCLE_AVOID_THREAD_SAFE_HASHTABLE_ITERATORS
+   As of v5.90, the Hashtable class includes logic to ensure that
+   HashtableIterators are thread safe, even if multiple threads are
+   iterating over the same Hashtable at the same time (as long the
+   Hashtable is not being modified, at least).  This extra safety
+   does impose some overhead, though -- about 16 bytes of RAM per
+   Hashtable object, and a small amount of CPU overhead imposed
+   by using an AtomicCounter.  If you want to avoid that overhead
+   and you're confident that you will always supply the 
+   HTIT_FLAG_NOREGISTER argument whenever you are doing 
+   concurrent iterations over a Hashtable (or Message), you can
+   supply this flag on the command line to avoid the overhead.
+
+-DMUSCLE_FAKE_SHARED_MEMORY
+   If defined, the SharedMemory class will allocate a non-shared memory
+   buffer (using muscleAlloc()) rather than actual shared memory.  Handy
+   for debugging if you suspect that shared-memory is causing a problem.
+
+-DMUSCLE_COUNT_STRING_COPY_OPERATIONS
+   If this flag is defined, the String class will tally the number
+   of times that String objects are moved and the number of times
+   they are copied.  This is handy for verifying that the C++11
+   move semantics are being used as expected.
+