// @(#)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