delegate.h

Go to the documentation of this file.

/*********************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*********************************************************************************/
 
#pragma once
 
#include <functional>
#include <type_traits>
 
namespace makVre
{
//! \brief Modern delegate class that can bind and invoke callables with any number of parameters
//! \tparam Ret Return type of the callback function
//! \tparam Args Parameter types for the callback function (variadic)
//!
//! This class provides a unified interface for binding and invoking different types of callables:
//! - Static/global functions
//! - Member functions bound to objects
//! - Lambda expressions
//! - Functors (classes with operator())
//!
//! The delegate uses type erasure via std::function internally while maintaining the ability
//! to compare and hash different delegate instances, which is useful for containers like
//! std::unordered_map or for implementing event systems.
//!
//! \note Delegates are hashable and comparable, but due to limitations in C++, lambdas with
//! identical code but at different source locations will be considered different delegates.
template <typename Ret, typename... Args>
class DtDelegate
{
public:
   //! \brief Enumeration of delegate types
   //!
   //! Categorizes the different types of callables that can be bound to a delegate.
   enum class DelegateType
   {
      Empty,  //!< Empty delegate with no bound callable
      Static, //!< Static or global function
      Member, //!< Member function bound to an object
      Lambda  //!< Lambda, functor, or other callable object
   };
 
   //! \brief Default constructor - creates an empty delegate
   //!
   //! Initializes a delegate with no bound callable. Calling an empty delegate
   //! will return a default-constructed instance of the return type.
   DtDelegate() = default;
 
   //! \brief Constructor binding a static or global function
   //! \param func Pointer to the static or global function to bind
   //!
   //! Creates a delegate that will invoke the specified static or global function
   //! when called.
   DtDelegate(Ret (*func)(Args...));
 
   //! \brief Constructor binding a class member function
   //! \tparam T Type of the object containing the member function
   //! \param object Pointer to the object instance
   //! \param method Pointer to the member function
   //!
   //! Creates a delegate that will invoke the specified member function on the
   //! given object instance when called.
   template <typename T, typename Method>
   DtDelegate(T* object, Method method);
 
   //! \brief Constructor binding a const class member function
   //! \tparam T Type of the object containing the member function
   //! \param object Pointer to the const object instance
   //! \param method Pointer to the const member function
   //!
   //! Creates a delegate that will invoke the specified const member function on
   //! the given const object instance when called.
   template <typename T, typename Method>
   DtDelegate(const T* object, Method method);
 
   //! \brief Constructor for any callable (lambda, functor, etc.)
   //! \tparam Callable Type of the callable object
   //! \param callable The callable object to bind
   //!
   //! Creates a delegate that will invoke the specified lambda or functor when
   //! called. The callable is stored by value, so any state within the callable
   //! is preserved.
   //!
   //! \note SFINAE is used to prevent this constructor from matching when
   //! a DtDelegate is passed, ensuring proper copy/move construction.
   template <typename Callable, typename = std::enable_if_t<!std::is_same_v<std::decay_t<Callable>, DtDelegate>>>
   DtDelegate(Callable&& callable);
 
   //! \brief Destructor
   ~DtDelegate() = default;
 
   //! \brief Copy constructor
   //! \param other The delegate to copy from
   //!
   //! Creates a new delegate that is a copy of the given delegate, including its
   //! bound callable and all associated hash information.
   DtDelegate(const DtDelegate& other);
 
   //! \brief Move constructor
   //! \param other The delegate to move from
   //!
   //! Creates a new delegate by moving the contents of the given delegate,
   //! leaving the source delegate in an empty state.
   DtDelegate(DtDelegate&& other) noexcept;
 
   //! \brief Copy assignment operator
   //! \param other The delegate to copy from
   //! \return Reference to this delegate after assignment
   //!
   //! Assigns the contents of the given delegate to this delegate, including its
   //! bound callable and all associated hash information.
   DtDelegate& operator=(const DtDelegate& other);
 
   //! \brief Move assignment operator
   //! \param other The delegate to move from
   //! \return Reference to this delegate after assignment
   //!
   //! Moves the contents of the given delegate to this delegate, leaving the
   //! source delegate in an empty state.
   DtDelegate& operator=(DtDelegate&& other) noexcept;
 
   //! \brief Reset the delegate to an empty state
   //!
   //! Clears the bound callable and resets all internal state, effectively
   //! returning the delegate to the same state as if it were default constructed.
   void reset() noexcept;
 
   //! \brief Function call operator with perfect forwarding (non-void return type)
   //! \tparam CallArgs Types of the arguments being passed to the delegate
   //! \param args Arguments to forward to the bound callable
   //! \return The result of invoking the bound callable with the given arguments
   //!
   //! Invokes the bound callable with the given arguments. If the delegate is empty:
   //! - For default constructible types: returns default-constructed instance (Ret{})
   //! - For non-default constructible types: throws std::runtime_error
   //! This overload is enabled only when the return type is not void.
   template <typename... CallArgs, typename = std::enable_if_t<!std::is_void_v<Ret>>>
   Ret operator()(CallArgs&&... args) const;
 
   //! \brief Function call operator with perfect forwarding (void return type)
   //! \tparam CallArgs Types of the arguments being passed to the delegate
   //! \param args Arguments to forward to the bound callable
   //!
   //! Invokes the bound callable with the given arguments. If the delegate is empty,
   //! this function simply returns without doing anything (silent no-op).
   //! This overload is enabled only when the return type is void.
   template <typename... CallArgs, typename = std::enable_if_t<std::is_void_v<Ret>>, typename = void>
   void operator()(CallArgs&&... args) const;
 
   //! \brief Check if the delegate has a bound callable
   //! \return true if a callable is bound, false otherwise
   //!
   //! Allows the delegate to be used in boolean contexts to check if it has a
   //! bound callable.
   explicit operator bool() const noexcept;
 
   //! \brief Get hash value for this delegate
   //! \return Hash value representing the delegate's bound callable
   //!
   //! Computes and returns a hash value that uniquely identifies the bound callable.
   //! This value is cached after computation for efficiency.
   //!
   //! \note For static functions and member functions, this will reliably reflect
   //! the identity of the function. For lambdas and functors, the hash is based on
   //! the object's address and type, which may differ between identical lambdas
   //! defined at different source locations.
   std::size_t hash() const noexcept;
 
   //! \brief Equality comparison operator using hash values
   //! \param rhs Right-hand side delegate to compare with
   //! \return true if delegates are equivalent, false otherwise
   //!
   //! Compares this delegate with another for equality based on their hash values.
   //! Two delegates are considered equivalent if they have the same type and:
   //! - For static functions: they point to the same function
   //! - For member functions: they point to the same method of the same object
   //! - For lambdas/functors: they are the same instance (by address and type)
   //!
   //! \note std::function does not support deep comparison of bound callables, so
   //! this comparison is based on the computed hash values.
   bool operator==(const DtDelegate& rhs) const noexcept;
 
   //! \brief Inequality comparison operator
   //! \param rhs Right-hand side delegate to compare with
   //! \return true if delegates are not equivalent, false otherwise
   //!
   //! Inverts the result of the equality operator.
   bool operator!=(const DtDelegate& rhs) const noexcept;
 
   //! \brief Get the type of this delegate
   //! \return The type of delegate (Empty, Static, Member, or Lambda)
   //!
   //! This function returns the type of the delegate, which can be useful for
   //! debugging and introspection. The type indicates what kind of callable
   //! entity is bound to the delegate:
   //! - Empty: No callable is bound
   //! - Static: A static or global function is bound
   //! - Member: A member function bound to an object is bound
   //! - Lambda: A lambda, functor, or other callable is bound
   DelegateType getType() const noexcept;
 
   //! \brief Helper function to hash method pointers
   //! \tparam Method Type of the method pointer
   //! \param method The method pointer to hash
   //! \return Hash value for the method pointer
   //!
   //! Creates a hash value from a method pointer by converting it to a byte sequence
   //! and hashing that sequence. This allows distinguishing between different methods
   //! of the same class.
   template <typename Method>
   static std::size_t hashMethodPtr(const Method& method) noexcept;
 
   //! \brief Helper function to hash any pointer (object or function)
   //! \tparam PtrType Type of the pointer
   //! \param ptr The pointer to hash
   //! \return Hash value for the pointer
   //!
   //! Creates a hash value from a pointer by using std::hash<const void*>.
   //! This is used to hash object pointers and function pointers.
   template <typename PtrType>
   static std::size_t hashPtr(PtrType ptr) noexcept;
 
   //! \brief Helper function to hash lambda objects
   //! \tparam Callable Type of the callable object
   //! \param callable The callable object to hash
   //! \return Hash value for the callable object
   //!
   //! Creates a hash value for a lambda or functor by combining the object's address
   //! and its type information. This allows distinguishing between different lambda
   //! expressions, even if they have identical code.
   template <typename Callable>
   static std::size_t hashLambda(const Callable& callable) noexcept;
 
protected:
   //! \brief Compute hash for the current delegate state
   //!
   //! Calculates a hash value based on the delegate's type and the specific bound callable.
   //! The hash computation differs based on the delegate type:
   //! - Empty: Hash is 0
   //! - Static: Hash is derived from the function pointer
   //! - Member: Hash combines the object pointer and method pointer
   //! - Lambda: Hash combines the lambda instance and its type
   //!
   //! Once computed, the hash is cached for future use.
   void computeHash() noexcept;
 
   //! \brief Reset hash computation state
   //!
   //! Clears the cached hash value and marks it as not computed, ensuring that
   //! the next call to hash() will recompute the value.
   void resetHash() const noexcept;
 
protected:
   //! \brief Function object to store any callable
   //!
   //! Uses std::function for type erasure, allowing the delegate to store and
   //! invoke any callable with the matching signature.
   std::function<Ret(Args...)> myFunction = nullptr;
 
   //! \brief Type of delegate
   //!
   //! Stores the category of the bound callable (Empty, Static, Member, or Lambda).
   DelegateType myType = DelegateType::Empty;
 
   //! \brief Hash of object pointer for member function delegates
   //!
   //! Stores the hash of the object pointer when binding a member function.
   //! Used to differentiate delegates bound to different object instances.
   std::size_t myObjectHash = 0;
 
   //! \brief Hash of static function pointer for static function delegates
   //!
   //! Stores the hash of the function pointer when binding a static function.
   //! Used to identify the specific function being called.
   std::size_t myStaticFuncHash = 0;
 
   //! \brief Hash value for method pointer to distinguish different member functions
   //!
   //! Stores the hash of the method pointer when binding a member function.
   //! Used to differentiate between different methods of the same class.
   std::size_t myMethodHash = 0;
 
   //! \brief Hash value for lambda objects
   //!
   //! Stores the hash of the lambda or functor when binding a callable object.
   //! Used to identify the specific callable being invoked.
   std::size_t myLambdaHash = 0;
 
   //! \brief Hash value for the delegate's bound callable
   //!
   //! Caches the computed hash value for efficient repeated access.
   //! This value combines information based on the delegate type.
   mutable std::size_t myHash = 0;
 
   //! \brief Flag to track if hash has been computed
   //!
   //! Indicates whether the hash value has been computed and cached.
   //! Used to avoid unnecessary recomputation of the hash.
   mutable bool myHashComputed = false;
};
 
} // namespace makVre
 
// Include template implementation
#include "vreUtil/delegate.inl"