EIC code displayed by LXR master/​include/​root/​TVirtualCollectionProxy.h	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

File indexing completed on 2025-01-18 10:12:33

 // @(#)root/cont:$Id$
 // Author: Philippe Canal 20/08/2003
 
 /*************************************************************************
  * Copyright (C) 1995-2003, Rene Brun, Fons Rademakers and al.           *
  * All rights reserved.                                                  *
  *                                                                       *
  * For the licensing terms see $ROOTSYS/LICENSE.                         *
  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
  *************************************************************************/
 
 #ifndef ROOT_TVirtualCollectionProxy
 #define ROOT_TVirtualCollectionProxy
 
 //////////////////////////////////////////////////////////////////////////
 //                                                                      //
 // TVirtualCollectionProxy                                              //
 //                                                                      //
 // Virtual interface of a proxy object for a collection class           //
 // In particular this is used to implement splitting, emulation,        //
 // and TTreeFormula access to STL containers.                           //
 //                                                                      //
 //////////////////////////////////////////////////////////////////////////
 
 #include "TClassRef.h"
 #include "TDataType.h"
 
 // Macro indicating the version of the Collection Proxy interface followed
 // by this ROOT build (See also Reflex/Builder/CollectionProxy.h).
 #define ROOT_COLLECTIONPROXY_VERSION 3
 
 class TClass;
 namespace TStreamerInfoActions {
    class TActionSequence;
 }
 
 // clang-format off
 /**
 \class TVirtualCollectionProxy
 \brief Defines a common interface to inspect/change the contents of an object that represents a collection
 
 Specifically, an object of a class that derives from TVirtualCollectionProxy relays accesses to any object that
 matches the proxied collection type.
 The interface provides two families of functions: (i) for direct manipulation, e.g. `Insert()` or `At()`; and
 (ii) iterator-based, e.g. `GetFunctionCreateIterators()` or `GetFunctionNext()`.
 TVirtualCollectionProxy objects are stateful; in particular, many functions require to set the object to operate
 on via `PushProxy()` / `PopProxy()`.  The `TPushPop` RAII class is provided for convenience.
 A collection proxy for a given class can be permanently set using `TClass::CopyCollectionProxy()`.
 The `Generate()` function should be overridden in derived classes to return a clean object of the most-derived class.
 */
 // clang-format on
 class TVirtualCollectionProxy {
 private:
    TVirtualCollectionProxy(const TVirtualCollectionProxy&) = delete;
    TVirtualCollectionProxy& operator=(const TVirtualCollectionProxy&) = delete;
 
 protected:
    TClassRef fClass;
    UInt_t    fProperties;
    friend class TClass;
 
 public:
    enum EProperty {
       // No longer used
       // kIsInitialized = BIT(1),
       kIsAssociative = BIT(2),
       kIsEmulated = BIT(3),
       /// The collection contains directly or indirectly (via other collection) some pointers that need explicit
       /// deletion
       kNeedDelete = BIT(4),
       kCustomAlloc = BIT(5) ///< The collection has a custom allocator.
    };
 
    /// RAII helper class that ensures that `PushProxy()` / `PopProxy()` are called when entering / leaving a C++ context
    class TPushPop {
    public:
       TVirtualCollectionProxy *fProxy;
       inline TPushPop(TVirtualCollectionProxy *proxy,
          void *objectstart) : fProxy(proxy) { fProxy->PushProxy(objectstart); }
       inline ~TPushPop() { fProxy->PopProxy(); }
    private:
       TPushPop(const TPushPop&) = delete;
       TPushPop& operator=(const TPushPop&) = delete;
    };
 
    TVirtualCollectionProxy() : fClass(), fProperties(0) {}
    TVirtualCollectionProxy(TClass *cl) : fClass(cl), fProperties(0) {}
    virtual ~TVirtualCollectionProxy() {}
 
    /// Returns a clean object of the actual class that derives from TVirtualCollectionProxy.  The caller is responsible
    /// for deleting the returned object.
    virtual TVirtualCollectionProxy *Generate() const = 0;
 
    /// Reset the information gathered from StreamerInfos and value's TClass.
    virtual Bool_t    Reset() { return kTRUE; }
 
    /// Return a pointer to the `TClass` representing the proxied _container_ class
    virtual TClass *GetCollectionClass() const { return fClass; }
 
    /// Return the type of the proxied collection (see enumeration TClassEdit::ESTLType)
    virtual Int_t GetCollectionType() const = 0;
 
    /// Return the offset between two consecutive in-memory values (which depends on the `sizeof()` and alignment of the
    /// value type).
    virtual ULong_t GetIncrement() const = 0;
 
    /// Return miscallenous properties of the proxy (see TVirtualCollectionProxy::EProperty)
    virtual Int_t GetProperties() const { return fProperties; }
 
    /// Construct a new container object and return its address
    virtual void *New() const { return !fClass.GetClass() ? nullptr : fClass->New(); }
    /// Construct a new container object at the address given by `arena`
    virtual void *New(void *arena) const { return !fClass.GetClass() ? nullptr : fClass->New(arena); }
    /// Construct a new container object and return its address
    virtual TClass::ObjectPtr NewObject() const
    {
       return !fClass.GetClass() ? TClass::ObjectPtr{} : fClass->NewObject();
    }
    /// Construct a new container object at the address given by `arena`
    virtual TClass::ObjectPtr NewObject(void *arena) const
    {
       return !fClass.GetClass() ? TClass::ObjectPtr{} : fClass->NewObject(arena);
    }
 
    /// Construct an array of `nElements` container objects and return the base address of the array
    virtual void *NewArray(Int_t nElements) const { return !fClass.GetClass() ? nullptr : fClass->NewArray(nElements); }
    /// Construct an array of `nElements` container objects at the address given by `arena`
    virtual void *NewArray(Int_t nElements, void *arena) const
    {
       return !fClass.GetClass() ? nullptr : fClass->NewArray(nElements, arena);
    }
    /// Construct an array of `nElements` container objects and return the base address of the array
    virtual TClass::ObjectPtr NewObjectArray(Int_t nElements) const
    {
       return !fClass.GetClass() ? TClass::ObjectPtr{} : fClass->NewObjectArray(nElements);
    }
    /// Construct an array of `nElements` container objects at the address given by `arena`
    virtual TClass::ObjectPtr NewObjectArray(Int_t nElements, void *arena) const
    {
       return !fClass.GetClass() ? TClass::ObjectPtr{} : fClass->NewObjectArray(nElements, arena);
    }
 
    /// Execute the container destructor
    virtual void Destructor(void *p, Bool_t dtorOnly = kFALSE) const
    {
       TClass* cl = fClass.GetClass();
       if (cl) cl->Destructor(p, dtorOnly);
    }
 
    /// Execute the container array destructor
    virtual void DeleteArray(void *p, Bool_t dtorOnly = kFALSE) const
    {
       TClass* cl = fClass.GetClass();
       if (cl) cl->DeleteArray(p, dtorOnly);
    }
 
    /// Return the `sizeof()` of the collection object
    virtual UInt_t Sizeof() const = 0;
 
    /// Set the address of the container being proxied and keep track of the previous one
    virtual void PushProxy(void *objectstart) = 0;
 
    /// Reset the address of the container being proxied to the previous container
    virtual void PopProxy() = 0;
 
    /// Return `true` if the content is of type 'pointer to'
    virtual Bool_t HasPointers() const = 0;
 
    /// If the value type is a user-defined class, return a pointer to the `TClass` representing the
    /// value type of the container.
    virtual TClass *GetValueClass() const = 0;
 
    /// If the value type is a fundamental data type, return its type (see enumeration EDataType).
    virtual EDataType GetType() const = 0;
 
    /// Return the address of the value at index `idx`
    virtual void *At(UInt_t idx) = 0;
 
    /// Clear the container
    virtual void Clear(const char *opt = "") = 0;
 
    /// Return the current number of elements in the container
    virtual UInt_t Size() const = 0;
 
    /// Allocates space for storing at least `n` elements.  This function returns a pointer to the actual object on
    /// which insertions should take place.  For associative collections, this function returns a pointer to a temporary
    /// buffer known as the staging area.  If the insertion happened in a staging area (i.e. the returned pointer !=
    /// proxied object), `Commit()` should be called on the value returned by this function.
    virtual void*     Allocate(UInt_t n, Bool_t forceDelete) = 0;
 
    /// Commits pending elements in a staging area (see Allocate() for more information).
    virtual void      Commit(void*) = 0;
 
    /// Insert elements into the proxied container.  `data` is a C-style array of the value type of the given `size`.
    /// For associative containers, e.g. `std::map`, the data type should be `std::pair<Key_t, Value_t>`.
    virtual void Insert(const void *data, void *container, size_t size) = 0;
 
    /// Return the address of the value at index `idx`
    char *operator[](UInt_t idx) const { return (char *)(const_cast<TVirtualCollectionProxy *>(this))->At(idx); }
 
    // Functions related to member-wise actions
    virtual TStreamerInfoActions::TActionSequence *GetConversionReadMemberWiseActions(TClass *oldClass, Int_t version) = 0;
    virtual TStreamerInfoActions::TActionSequence *GetReadMemberWiseActions(Int_t version) = 0;
    virtual TStreamerInfoActions::TActionSequence *GetWriteMemberWiseActions() = 0;
 
    /// The size of a small buffer that can be allocated on the stack to store iterator-specific information
    static const Int_t fgIteratorArenaSize = 16; // greater than sizeof(void*) + sizeof(UInt_t)
 
    /// `*begin_arena` and `*end_arena` should contain the location of a memory arena of size `fgIteratorArenaSize`.
    /// If iterator-specific information is of that size or less, the iterators will be constructed in place in the given
    /// locations.  Otherwise, iterators will be allocated via `new` and their address returned by modifying the value
    /// of `*begin_arena` and `*end_arena`.
    /// As a special case, given that iterators for array-backed containers are just pointers, the required information
    /// will be directly stored in `*(begin|end)_arena`.
    typedef void (*CreateIterators_t)(void *collection, void **begin_arena, void **end_arena, TVirtualCollectionProxy *proxy);
 
    /// Return a pointer to a function that can create an iterator pair, where each iterator points to the begin and end
    /// of the collection, respectively (see CreateIterators_t).  If `read == kTRUE`, data is to be read from disk, i.e.
    /// written to the in-memory collection.
    virtual CreateIterators_t GetFunctionCreateIterators(Bool_t read = kTRUE) = 0;
 
    /// Copy the iterator `source` into `dest`.  `dest` should contain the location of a memory arena of size
    /// `fgIteratorArenaSize`.
    /// If iterator-specific information is of that size or less, the iterators will be constructed in place in the given
    /// locations.  Otherwise, iterators will be allocated via `new` and their address returned by modifying the value
    /// of `*begin_arena` and `*end_arena`.  The actual address of the iterator is returned in any case.
    typedef void* (*CopyIterator_t)(void *dest, const void *source);
 
    /// Return a pointer to a function that can copy an iterator (see CopyIterator_t).  If `read == kTRUE`, data is to be
    /// read from disk, i.e. written to the in-memory collection.
    virtual CopyIterator_t GetFunctionCopyIterator(Bool_t read = kTRUE) = 0;
 
    /// `iter` and `end` should be pointers to an iterator to be incremented and an iterator that points to the end of
    /// the collection, respectively.  If `iter` has not reached the end of the collection, this function increments the
    /// iterator and returns a pointer to the element before the increment.  Otherwise, `nullptr` is returned.
    typedef void* (*Next_t)(void *iter, const void *end);
 
    /// Return a pointer to a function that can advance an iterator (see Next_t).  If `read == kTRUE`, data is to be
    /// read from disk, i.e. written to the in-memory collection.
    virtual Next_t GetFunctionNext(Bool_t read = kTRUE) = 0;
 
    /// If the size of the iterator is greater than `fgIteratorArenaSize`, call delete on the addresses; otherwise, just
    /// call the iterator's destructor.
    typedef void (*DeleteIterator_t)(void *iter);
    typedef void (*DeleteTwoIterators_t)(void *begin, void *end);
 
    /// Return a pointer to a function that can delete an iterator (pair) (see DeleteIterator_t).  If `read == kTRUE`,
    /// data is to be read from disk, i.e. written to the in-memory collection.
    virtual DeleteIterator_t GetFunctionDeleteIterator(Bool_t read = kTRUE) = 0;
    virtual DeleteTwoIterators_t GetFunctionDeleteTwoIterators(Bool_t read = kTRUE) = 0;
 };
 
 #endif

This page was automatically generated by the 2.3.7 LXR engine. The LXR team