---

CdbBdbSRallocatorP.ddl

Go to the documentation of this file.

#ifndef CDBBDBSHARED_R_ALLOCATOR_P_HH
#define CDBBDBSHARED_R_ALLOCATOR_P_HH

// File and Version Information:
//      $Id: CdbBdbSRallocatorP.ddl,v 1.5 2004/08/06 05:54:25 bartoldu Exp $

#include "BdbUtil/Bdb.hh"

#include "CdbBase/CdbItr.hh"
#include "CdbBdbShared/CdbBdbSBtreeP.hh"

#include <iostream>

/// Default RT_OPERATIONS_POLICY policy for a resource type class
/**
  * The resource type is specified through the template parameter of
  * this class.
  */
template< class RT >
class CdbBdbSRaDefaultPolicy {
public:

    static RT   min  ( )                 { return 0;       }
    static RT   next ( RT value )        { return ++value; }
    static bool valid( const RT& value ) { return true;    }
};

/// Generic resource allocator class
/**
    This persistent class represents "resource allocator", whose primary
    focus (although not limited to) is
    at various sorts of identifiers. This facility is capable of managing
    individual values (not ranges) of resources.

    The class has the following template parameters:

        RT: the type of the managed resource. This class is expected
            to provide the following public interface:

            - default ctor
            - copy ctor
            - destructor
            - assignment operator
            - operator==
            - operator<
            - operator << to serialize into std::ostream

            Basically, it's the same interface, which is required to put objects
            of the RT type into a B-tree.

        RT_OPERATIONS_POLICY: an optional policy for the RT type. The role
                              of this policy is to supply an appropriate abstraction
                              for the following operations:

           - obtain a value of RT type in its minimum state

           - increment a value of RT type to get to the next element in a sequence
             of allowed ones (logically similar to ++(value) operator).

             IMPORTANT: It's assumed that when the iterated value will reach its maximum
                        available state then the iterator will switch back to the minimum
                        state as defined above.

           - check if specified value of a resource is in a "valid" range.

             IMPORTANT: The "Resource Allocator" neither assumes an existence nor relies at
                        any internal state the RT_OPERATIONS_POLICY class may have.
                        It means that the methods of a concrete policy classs supplied
                        through this template parameter can be invoked at any sequence
                        and they will always provide repeatable results for the same
                        values of their input parameters.

           See the interface of the default RT_OPERATIONS_POLICY class as a specification
           for the interface of user-defined policy classes.

    This class also provides default version of the RT_OPERATIONS_POLICY class, which
    is sufficient enough for most primitive ("countable") data types like: d_ULong, d_UShort,
    etc. The default implementation of the RT_OPERATIONS_POLICY relies on the following:

    - there is proper (and semantically meaningfull) conversion for the RT
      to set it to its minimum state by assigning 0 to it.

    - there is ++(value) operator to advance the value to the "next" state

    - the values obtained through the "operator++" are unique and sequential
      in a range of the available value of the RT type.

    - all possible values of the RT type are "valid".

    The abstract user defined types require proper policy class to be supplied
    along with RT type to override the default policy unless the RT type
    has sufficient (both formally and semantically) public interface
    meeting the requirements of the default implementation for OPERATIONS.

  */
template< class RT,
          class RT_OPERATIONS_POLICY = CdbBdbSRaDefaultPolicy<RT> >
class CdbBdbSRallocatorP : public BdbPersObj {

public:

  /// Default constructor
  /**
    * Initializes an empty collectiuon
    */
    CdbBdbSRallocatorP( );

  /// Destructor
  /**
    * Will also destroy all the elements.
    */
    virtual ~CdbBdbSRallocatorP( );

  /// Check allocation of specified resource
  /**
    * The method will return:
    *
    *     - "Success"  if specified resource is allocated
    *     - "NotFound" if specified resource is not allocated
    *     - "Error"    if specified resource is not "valid" (see RT_OPERATIONS_POLICY::valid()
    *                  method for the explanation) or in case of any other internal problem
    */
    virtual CdbStatus isAllocated( const RT& theResource ) const;

  /// Force allocation of specified resource
  /**
    * The method makes sure that specified resource, whose value passed to the procedure
    * gets allocated. The passed resource can already be allocated.
    *
    * The method will return:
    *
    *     - "Success"  if specified resource already was or just has been allocated
    *     - "Error"    if specified resource is not "valid" (see RT_OPERATIONS_POLICY::valid()
    *                  method for the explanation) or in case of any other internal problem
    */
    virtual CdbStatus force( const RT& theResource );

  /// Allocate a resource
  /**
    * The method will return:
    *
    *     - "Success"  if a resource has been allocated
    *     - "NotFound" if a resource could not be allocated
    */
    virtual CdbStatus allocate( RT& theResource );

  /// Release specified resource
  /**
    * The method will return:
    *
    *     - "Success"  if specified resource was released
    *     - "NotFound" if specified resource was never allocated
    *     - "Error"    if specified resource is not "valid" (see RT_OPERATIONS_POLICY::valid()
    *                  method for the explanation) or in case of any other internal problem
    */
    virtual CdbStatus release( const RT& theResource );

  /// Get an instance of an iterator for allocated resources
  /**
    * This kind of iterator provides "non-sorted" access to the values
    * of allocated resources.
    */
    virtual CdbItr<RT> iterator( ) const;

  /// Dump the contents of the object
  /**
    */
    virtual void dump( std::ostream& o ) const;

private:

  // Two indexes: one for allocated resources and the other one -
  //              for the spare ones.

    BdbRef( CdbBdbSBtreeP< RT > ) _allocatedRef;
    BdbRef( CdbBdbSBtreeP< RT > ) _freeRef;

  // The value of the most recently generated resource. It will be
  // automatically updated at an allocation request if the
  // index of spare resources is empty.
  //
  // NOTE: The "force" request may violate the normal sequence of resources
  //       allocation. Therefore if the next value generated through the data member
  //       below is already occupied (at either of indexes above) then the generator
  //       will skip the value and go to the next one and so on until a spare one
  //       will be found or the allocation will be exausted.

    RT _recent;
};

// Explicit template instantiation for the resource allocator

#define EXPLICIT_INSTANTIATE_CdbBdbSRallocatorP_1( T ) \
EXPLICIT_INSTANTIATE_CdbBdbSBtreeP_1( T ); \
template class CdbBdbSRallocatorP< T >

#ifdef    BABAR_COMP_INST
#include "CdbBdbShared/CdbBdbSRallocatorP.cc"
#endif /* BABAR_COMP_INST */

#endif /* CDBBDBSHARED_R_ALLOCATOR_P_HH */

---