ValMem.hpp

Go to the documentation of this file.

/*
---------------------------------------------------------------------------

    This file is part of uHAL.

    uHAL is a hardware access library and programming framework
    originally developed for upgrades of the Level-1 trigger of the CMS
    experiment at CERN.

    uHAL 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.

    uHAL 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 uHAL.  If not, see <http://www.gnu.org/licenses/>.


      Andrew Rose, Imperial College, London
      email: awr01 <AT> imperial.ac.uk

      Marc Magrans de Abril, CERN
      email: marc.magrans.de.abril <AT> cern.ch

---------------------------------------------------------------------------
*/

#ifndef _uhal_ValMem_hpp_
#define _uhal_ValMem_hpp_

#include <cstddef>                 // for size_t
#include <deque>
#include <vector>
#include <stdint.h>                // for uint32_t, uint8_t

#include <boost/shared_ptr.hpp>

#include "uhal/log/exception.hpp"
#include "uhal/definitions.hpp"




namespace uhal
{
  namespace exception
  {
    UHAL_DEFINE_EXCEPTION_CLASS ( NonValidatedMemory , "Exception class to handle the case of attempted access on unvalidated memory." )
    UHAL_DEFINE_EXCEPTION_CLASS ( ValMemImutabilityViolation , "Exception class to handle the case of attempted modification of validated memory." )
  }

  // Forward declare ClientInterface so it can be our friend
  class ClientInterface;


  // Forward declaration so we can define friends
  class ValHeader;
  // Forward declaration so we can define friends
  template< typename T > class ValWord;
  // Forward declaration so we can define friends
  template< typename T > class ValVector;


  struct _ValHeader_
  {
    public:
      bool valid;
      std::deque<uint32_t> IPbusHeaders;

    protected:
      friend class ValHeader;
      _ValHeader_ ( const bool& aValid );
  };



  template< typename T >
  struct _ValWord_ : public _ValHeader_
  {
    public:
      T value;
      // //! A flag for marking whether the data is actually valid
      // bool valid;
      uint32_t mask;
      // //! The IPbus header associated with the transaction that returned this data
      // uint32_t IPbusHeader;

    protected:
      friend class ValWord<T>;
      _ValWord_ ( const T& aValue , const bool& aValid , const uint32_t aMask );
  };


  template< typename T >
  struct _ValVector_ : public _ValHeader_
  {
    public:
      std::vector<T> value;
      // //! A flag for marking whether the data is actually valid
      // bool valid;
      // //! The IPbus header associated with the transaction that returned this data
      // std::deque<uint32_t> IPbusHeaders;

    protected:
      friend class ValVector<T>;
      _ValVector_ ( const std::vector<T>& aValue , const bool& aValid );
  };



  class ValHeader
  {
      friend class ClientInterface;

    public:
      ValHeader();

      template< typename T >
      ValHeader ( const ValWord<T>& aValWord );

      template< typename T >
      ValHeader ( const ValVector<T>& aValVector );


      bool valid();
      void valid ( bool aValid );

      // /**
      // Return a std::deque containing all the IPbus headers returned during the transaction
      // @return a std::deque containing all the IPbus headers returned during the transaction
      // @note This is a deque, since a block transaction may be chunked into many smaller block transactions
      // */
      // const std::deque<uint32_t>& returnedHeaders();

    protected:
      boost::shared_ptr< _ValHeader_ > mMembers;
  };


  template< typename T >
  class ValWord
  {

      friend class ClientInterface;

      friend class ValHeader;

    public:
      ValWord ( const T& aValue , const uint32_t& aMask = defs::NOMASK );
      ValWord ( const ValWord<T>& aVal );
      ValWord();
      bool valid();
      void valid ( bool aValid );
      ValWord& operator = ( const T& aValue );
      operator T();
      T value() const;
      void value ( const T& aValue );
      const uint32_t& mask() const;
      void mask ( const uint32_t& aMask );

      // /**
      // Return a std::deque containing all the IPbus headers returned during the transaction
      // @return a std::deque containing all the IPbus headers returned during the transaction
      // @note This is a deque, since a block transaction may be chunked into many smaller block transactions
      // */
      // const std::deque<uint32_t>& returnedHeaders();

    private:
      boost::shared_ptr< _ValWord_<T> > mMembers;

  };


  template< typename T >
  class ValVector
  {
      friend class ClientInterface;

      friend class ValHeader;

    public:
      typedef typename std::vector< T >::iterator iterator;
      typedef typename std::vector< T >::const_iterator const_iterator;
      typedef typename std::vector< T >::reverse_iterator reverse_iterator;
      typedef typename std::vector< T >::const_reverse_iterator const_reverse_iterator;

    public:
      ValVector ( const std::vector<T>& aValues );
      ValVector ( const ValVector& aValues );
      ValVector ( const uint32_t& aSize );
      ValVector();
      bool valid();
      void valid ( bool aValid );
      template <class InputIterator> void assign ( InputIterator aBegin , InputIterator aEnd );
      void push_back ( const T& aValue );
      const T& operator[] ( std::size_t aIndex ) const;
      const T& at ( std::size_t aIndex ) const;
      std::size_t size() const;
      void clear();
      const_iterator begin() const;
      const_iterator end() const;
      const_reverse_iterator rbegin() const;
      const_reverse_iterator rend() const;
      std::vector<T> value() const;
      void value ( const std::vector<T>& aValue );

      /*
                / **
                    If the memory has not previously been marked as valid, return a iterator to the beginning of the underlying memory
                    @return a iterator to the beginning of the underlying memory
                * /
                iterator begin();
                / **
                    If the memory has not previously been marked as valid, return a iterator to the end (one past last entry) of the underlying memory
                    @return a iterator to the end (one past last entry) of the underlying memory
                * /
                iterator end();
                / **
                    If the memory has not previously been marked as valid, return a reverse iterator to the reverse beginning (the last entry) of the underlying memory
                    @return a reverse iterator to the reverse beginning (the last entry) of the underlying memory
                * /
                reverse_iterator rbegin();
                / **
                    If the memory has not previously been marked as valid, return a reverse iterator to the reverse end (one before the zero'th entry) of the underlying memory
                    @return a reverse iterator to the reverse end (one before the zero'th entry) of the underlying memory
                * /
                reverse_iterator rend();
      */

      // /**
      // Return a std::deque containing all the IPbus headers returned during the transaction
      // @return a std::deque containing all the IPbus headers returned during the transaction
      // @note This is a deque, since a block transaction may be chunked into many smaller block transactions
      // */
      // const std::deque<uint32_t>& returnedHeaders();

    private:
      boost::shared_ptr< _ValVector_<T> > mMembers;

  };

}

#include "uhal/TemplateDefinitions/ValMem.hxx"

#endif