partitionSafety.hpp

// partition:  a container for organizing a set of sequential integers
//             into non-overlapping groups.
// Version:    0.1.1
// Copyright 2013 Matthew T. Busche.
//
// This program is free software:  you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation, either version 3 of the License, or (at your option)
// any later version.
//
// This program is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
// more details.
//
// You should have received a copy of the GNU General Public License along
// with this program.  If not, see <http://www.gnu.org/licenses/>.

#ifndef PARTITIONSAFETY_HPP
#define PARTITIONSAFETY_HPP

// Methods of Domain, Group, Group::Iterator and Group::ConstIterator validate
// caller input and verify that the state of the invoked object is compatible
// with the requested action, throwing exceptions when checks fail.  Examples
// include:
//
//    o Verifying that the id used to request a member mapping is within the
//      Domain's range.
//
//    o Verifying that a Group has been bound to a Domain before allowing a
//      caller to add members to that Group.
//
//    o Verifying that a Group Iterator is not pointing to the position
//      before the front or after the back of the Group list before
//      allowing the iterator to be dereferenced.
//
// Most checks have small overhead compared to the cost of the methods they
// safeguard; however, safety checks for some methods (like an iterator
// dereference) may be responsible for a significant fraction of the total
// processing of the method.  The preprocessor macro PARTITION_SL (partition
// safety level) can be modified to eliminate some (or all) validations to
// achieve performance gains which may be useful to some programs.
// PARTITION_SL settings from 0 to 4 provide different levels of partition
// safety as summarized here:
// 
//    0 : No validations are performed for any method.
//
//    1 : Validates constructor input and validates inputs that manipulate either
//        the size of the Domain or the amount of memory reserved for the Domain.
//        (It is expected that constructor and resize/reserve operations will
//        be rare for the typical program and validating the inputs for these
//        operations will not measurably impact performance.)
//
//    2 : Includes all other validations except validations in Iterator methods.
//        (Iterator methods are quite short and are perhaps most impacted
//        by their associated validation checks, so these validations are
//        relegated to level 3.)
//        
//    3 : Includes all validations.
//
//    4 : This level provides no additional validation but includes code that
//        zeroes out certain data fields as an aid to debugging.  (For example
//        PARTITION_SL 4 ensures that the _prev and _next pointers of the
//        Node structure are zeroed out when the Node is not in a Group list.
//
// Most programs that use partition will not measurably benefit from the
// removal of safety validations.  Of those that do, a simple change to the
// PARTITION_SL setting will usually be adequate to eliminate undesirable
// safety overhead; but finer controls are provided that allow safety checks
// for specific groups of partition methods to be enabled or disabled.
//
// Class methods are organized into similar functional groups.  Each group is
// assigned an independent preprocessor safety threshold setting.  For
// example, all Iterator methods that dereference the iterator are assigned
// the preprocessor safety threshold setting PARTITION_ST_ITERATOR_DEREF.  The
// validation checks for all methods in this functional group are included by
// the preprocessor if the value of PARTITION_SL is at least the value of
// PARTITION_ST_ITERATOR_DEREF.  For clarity, here is an example of one method
// implementation:
//
//        template<typename M, typename V>
//        inline const typename Domain<M,V>::Entry& Group<M,V>::ConstIterator::operator*() const
//        {
//    #if PARTITION_SL >= PARTITION_ST_ITERATOR_DEREF
//            _verifyNotAtEnd("operator*()");
//    #endif
//            return _node->_entry;
//        }
//
// Lowering PARTITION_SL to any setting below the default value of
// PARTITION_ST_ITERATOR_DEREF will disable these safety checks, but that may
// also disable other safety checks you'd rather leave enabled.  To disable
// safety checks only on methods that dereference iterators, instead raise the
// setting of PARTITION_ST_ITERATOR_DEREF to some number greater than
// PARTITION_SL.  The default value of the partition safety level
// (PARTITION_SL) and the list of functional groups along with their
// respective default safety threshold settings (PARTITION_ST_*) are defined
// below.


// Default PARTITION_SL
//
#ifndef PARTITION_SL
#define PARTITION_SL 3
#endif

// Default DEBUG threshold
//
#ifndef PARTITION_ST_DEBUG
#define PARTITION_ST_DEBUG 4
#endif

// Default threshold for Domain constructors.
//
#ifndef PARTITION_ST_DOMAIN_CONSTRUCTOR
#define PARTITION_ST_DOMAIN_CONSTRUCTOR 1
#endif

// Default threshold for operations that either resize the Domain or modify
// the amount of memory reserved for the Domain.
//
#ifndef PARTITION_ST_DOMAIN_MEMORY
#define PARTITION_ST_DOMAIN_MEMORY 1
#endif

// Default threshold for operations that access (for reading or writing)
// existing members of the Domain.
//
#ifndef PARTITION_ST_DOMAIN_ACCESSOR
#define PARTITION_ST_DOMAIN_ACCESSOR 2
#endif

// Default threshold for Group constructors.
//
#ifndef PARTITION_ST_GROUP_CONSTRUCTOR
#define PARTITION_ST_GROUP_CONSTRUCTOR 1
#endif

// Default threshold for operations that read existing members of the Group.
// (This does include the non-const version of find.)
//
#ifndef PARTITION_ST_GROUP_ACCESSOR
#define PARTITION_ST_GROUP_ACCESSOR 2
#endif

// Default threshold for operations that add new members to a Group.
//
#ifndef PARTITION_ST_GROUP_ADD
#define PARTITION_ST_GROUP_ADD 2
#endif

// Default threshold for operations that remove members from a Group.
//
#ifndef PARTITION_ST_GROUP_REMOVE
#define PARTITION_ST_GROUP_REMOVE 2
#endif

// Default threshold for the Iterator's ++ and -- operators.
//
#ifndef PARTITION_ST_ITERATOR_INC
#define PARTITION_ST_ITERATOR_INC 3
#endif

// Default threshold for operations that dereference the iterator.  (Note that
// validations for the Iterator::beforeFront() and Iterator::afterBack() are
// goverend by this threshold.  Although these methods do not access the
// internal Node structure pointed to by the Iterator, they do dereference the
// Iterator's Group pointer.)
//
#ifndef PARTITION_ST_ITERATOR_DEREF
#define PARTITION_ST_ITERATOR_DEREF 3
#endif

// Default threshold for operations that compare two iterators.
// (Comparing iterators from different groups is considered
// erroneous.)
//
#ifndef PARTITION_ST_ITERATOR_COMPARE
#define PARTITION_ST_ITERATOR_COMPARE 3
#endif

// *****************************
// *** FOR INTERNAL USE ONLY ***
// *****************************
//
// The remaining preprocessor definitions are used internally to conditionally
// include verification tests.
//
#if PARTITION_SL >= PARTITION_ST_DOMAIN_CONSTRUCTOR
#define PARTITION_SAFETY_DOMAIN_CONSTRUCTOR(x) x
#else
#define PARTITION_SAFETY_DOMAIN_CONSTRUCTOR(x)
#endif

#if PARTITION_SL >= PARTITION_ST_DOMAIN_MEMORY
#define PARTITION_SAFETY_DOMAIN_MEMORY(x) x
#else
#define PARTITION_SAFETY_DOMAIN_MEMORY(x)
#endif

#if PARTITION_SL >= PARTITION_ST_DOMAIN_ACCESSOR
#define PARTITION_SAFETY_DOMAIN_ACCESSOR(x) x
#else
#define PARTITION_SAFETY_DOMAIN_ACCESSOR(x)
#endif

#if PARTITION_SL >= PARTITION_ST_GROUP_CONSTRUCTOR
#define PARTITION_SAFETY_GROUP_CONSTRUCTOR(x) x
#else
#define PARTITION_SAFETY_GROUP_CONSTRUCTOR(x)
#endif

#if PARTITION_SL >= PARTITION_ST_GROUP_ACCESSOR
#define PARTITION_SAFETY_GROUP_ACCESSOR(x) x
#else
#define PARTITION_SAFETY_GROUP_ACCESSOR(x)
#endif

#if PARTITION_SL >= PARTITION_ST_GROUP_ADD
#define PARTITION_SAFETY_GROUP_ADD(x) x
#else
#define PARTITION_SAFETY_GROUP_ADD(x)
#endif

#if PARTITION_SL >= PARTITION_ST_GROUP_REMOVE
#define PARTITION_SAFETY_GROUP_REMOVE(x) x
#else
#define PARTITION_SAFETY_GROUP_REMOVE(x)
#endif

#if PARTITION_SL >= PARTITION_ST_INTERATOR_INC
#define PARTITION_SAFETY_INTERATOR_INC(x) x
#else
#define PARTITION_SAFETY_INTERATOR_INC(x)
#endif

#if PARTITION_SL >= PARTITION_ST_ITERATOR_DEREF
#define PARTITION_SAFETY_ITERATOR_DEREF(x) x
#else
#define PARTITION_SAFETY_ITERATOR_DEREF(x)
#endif

#if PARTITION_SL >= PARTITION_ST_ITERATOR_COMPARE
#define PARTITION_SAFETY_ITERATOR_COMPARE(x) x
#else
#define PARTITION_SAFETY_ITERATOR_COMPARE(x)
#endif

#endif