---

CdbBdbSPagedVarrayP.ddl

Go to the documentation of this file.

#ifndef CDBBDBSHARED_PAGED_VARRAY_P_HH
#define CDBBDBSHARED_PAGED_VARRAY_P_HH

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

#include "BdbUtil/Bdb.hh"

#include "CdbBdbShared/CdbBdbSLeafNodeP.hh"
#include "CdbBdbShared/CdbBdbSDirectoryNodeP.hh"

#include <iostream>

/// Paged variable size array
/**
  * This is a persistent ordered collection of elements of the same type, which
  * is specified through the template parameter..
  *
  * ATTENTION: Objectivity/DB requires to use explicit template instamtiation
  *            for each actual type this collection is instantiated with.
  *            Use convenience macros at the end of thsi file.
  */
template< typename E >
class CdbBdbSPagedVarrayP : public BdbPersObj {

public:

    typedef E ElementType;

public:

  /// Constructors
  /**
    * The optional parameters list of this constructr includes:
    *
    *   - the initial number of elements to allocate
    *   - the number of elements (of type E) per leaf node.
    *   - the number of links to other nodes per directory node.
    *
    * If default 0 is passed instead of any of last two paremeters then
    * the corresponding default value will be used. The default value is
    * calculated from the size of the Objectivity/DB page (see the BOOT
    * file of the federation) and the size of elements stored on that
    * page.
    */
    CdbBdbSPagedVarrayP( d_ULong theInitialSize     = 0,
                         d_ULong theNumPerLeaf      = 0,
                         d_ULong theNumPerDirectory = 0 );

  /// Destructor

    virtual ~CdbBdbSPagedVarrayP( );

  /// Get the current size of the array
  /**
    * Returns the actual size of the array as it was specified either through
    * the parameter of the constructor or as a results of subsequent calles
    * to "resize" method.
    */
    d_ULong size( ) const;

  /// Resize the array
  /**
    * As usually, if this number is less than the current size than the tail
    * will be destroyed. If bigger - then default constructor for the remaining
    * elements will be called.
    *
    * @return the completion status
    */
    BdbStatus resize( d_ULong theNewSize );

  /// Array subscript operator
  /**
    * Returns a reference onto an element. Given this reference the referred
    * element can be modified/replaced.
    *
    * WARNING: The result is unpredictable if the elements exceeds
    *          the array's bounds.
    */
/*
 * ATTENTION: Using virtual memory references is unsafe in persistent world
 *            since the (Objectivity) cache is out of our control.
 *            It's true for both read and write operations.
 *
 *            This is why we use two explicit (read/write) operations with values
 *            instead of this subscript operator. The only reason we still have
 *            this operator here is to attract attention to this problem.
 *
 *  E& operator[]( d_ULong theIndex );
 */

  /// Set a value of an element at specified location
  /**
    * This method is meant to be used when the element at specified
        * location is going to be modified/replaced.
    *
    * WARNING: The result is unpredictable if the elements exceeds
    *          the array's bounds.
    */
    void setElementAt( d_ULong  theIndex,
                       const E& value );

  /// Get a reference onto an element (const)
  /**
    * Returns a copy (!) of an element. The returned element is only available
    * for read. The copy is returned because there is no guarantee that a page
        * where the element is located at will be locked in the virtual memory.
    *
    * WARNING: The result is unpredictable if the elements exceeds
    *          the array's bounds.
    */
    E elementAt( d_ULong theIndex ) const;

  /// Dump the structure and (optionaly) the contents of the array
  /**
    * The contents of the array is only dumped if specified glag is set up.
    */
    void dump( std::ostream& o,
               bool     dumpContentsFlag = false ) const;

private:

  /// Calculate the number of levels for specified size
  /**
    * The culculation takes into account the parameters of paging
        * (number of elements per lef and directory nodes).
    */
    d_ULong calculateNumLevels( d_ULong theSize ) const;

  /// Get default number of elements per leaf node
  /**
    */
    d_ULong defaultNumPerLeaf( ) const;

  /// Get default number of elements per directory node
  /**
    */
    d_ULong defaultNumPerDirectory( ) const;

private:

  // These two parameters are calculated at the object construction
  // and never get changed during the object's lifetime.

    d_ULong _numPerLeaf;        // Number of elements of type E per LEAF node
    d_ULong _numPerDirectory;   // Number of links to other nodes from a LEAF node

  // The following parameters change depending on the size of the array
  // and the values of the above given parameters.

    d_ULong _numLevels;         // The depth of the indexing tree (0..n)
    d_ULong _size;              // The actual size of the array.

  // The initial data node is only used when the current size of the array
  // does not exceed the value of above given "_numPerLeaf" parameter. Otherwise
  // its reference is set to 0.
  //
  // The initial directory node is used in an opposite case. Otherwise its
  // reference is set to 0.

    BdbRef(CdbBdbSLeafNodeP<E>)      _leafNode;         // Initial leaf node      (optional)
    BdbRef(CdbBdbSDirectoryNodeP<E>) _directoryNode;    // Initial directory node (optional)
};

/// Macros for the explicit template instantiation any types of elements.
/**
  * The macro will provide all the necessary declarations for arbitrary
  * type of elements (including the predefined "primitive" ones). This instantiation
  * is required by Objectivity/DDL compilation system to put the new classes into
  * the federation's schema.
  *
  * The actual instantiation for primitive types is done in separate files.
  *
  * GENERAL NOTE: Be carefull when doing explicit template instantiations
  *               in Objectivity/DDL API to avoid potential library conflicts
  *               when the same template is defined in two or more packages
  *               (libraries)!!!
  *
  *               As a solution put a common instance of a template into one package
  *               and use it from there.
  *
  * There are two forms of macros. The first parameter (or group of thoses if
  * a value of teh parameter is template itself) of both forms is a type of elements.
  *
  * The second 'TN' parameter will also introduce new type as required by a user.
  *
  * NOTE: This macro can't be used to instantiate an array of "ooBoolean" type
  *       because this type may conflicts with "ooInt8" on some platforms.
  */
#define instantiate_CdbBdbSPagedVarrayP( T , TN ) \
template class CdbBdbSNodeP         < T >; \
template class CdbBdbSLeafNodeP     < T >; \
template class CdbBdbSDirectoryNodeP< T >; \
template class CdbBdbSPagedVarrayP  < T >; \
typedef CdbBdbSPagedVarrayP         < T > TN

#define EXPLICIT_INSTANTIATE_CdbBdbSPagedVarrayP_1( T ) \
template class CdbBdbSNodeP         < T >; \
template class CdbBdbSLeafNodeP     < T >; \
template class CdbBdbSDirectoryNodeP< T >; \
template class CdbBdbSPagedVarrayP  < T >

#define EXPLICIT_INSTANTIATE_CdbBdbSPagedVarrayP_2( T1 , T2 ) \
template class CdbBdbSNodeP         < T1 , T2 >; \
template class CdbBdbSLeafNodeP     < T1 , T2 >; \
template class CdbBdbSDirectoryNodeP< T1 , T2 >; \
template class CdbBdbSPagedVarrayP  < T1 , T2 >

#define EXPLICIT_INSTANTIATE_CdbBdbSPagedVarrayP_3( T1, T2 , T3 ) \
template class CdbBdbSNodeP         < T1 , T2 , T3 >; \
template class CdbBdbSLeafNodeP     < T1 , T2 , T3 >; \
template class CdbBdbSDirectoryNodeP< T1 , T2 , T3 >; \
template class CdbBdbSPagedVarrayP  < T1 , T2 , T3 >

// Template class implementation

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

#endif /* CDBBDBSHARED_PAGED_VARRAY_P_HH */

---