ns3::Callback< R, UArgs > Class Template Reference

Callback template class. More...

#include "callback.h"

Inherits ns3::CallbackBase.

Collaboration diagram for ns3::Callback< R, UArgs >:

Public Member Functions
	Callback ()
template<typename... BArgs>
	Callback (const Callback< R, BArgs..., UArgs... > &cb, BArgs... bargs)
	Construct from another callback and bind some arguments (if any)
	Callback (const Ptr< CallbackImpl< R, UArgs... > > &impl)
	Construct from a CallbackImpl pointer.
template<typename T, typename... BArgs, std::enable_if_t<!std::is_base_of_v< CallbackBase, T > &&std::is_invocable_r_v< R, T, BArgs..., UArgs... >, int > = 0>
	Callback (T func, BArgs... bargs)
	Construct from a function and bind some arguments (if any)
bool	Assign (const CallbackBase &other)
	Adopt the other's implementation, if type compatible.
template<typename... BoundArgs>
auto	Bind (BoundArgs &&... bargs)
	Bind a variable number of arguments.
bool	CheckType (const CallbackBase &other) const
	Check for compatible types.
bool	IsEqual (const CallbackBase &other) const
	Equality test.
bool	IsNull () const
	Check for null implementation.
void	Nullify ()
	Discard the implementation, set it to null.
R	operator() (UArgs... uargs) const
	Functor with varying numbers of arguments.
Public Member Functions inherited from ns3::CallbackBase
	CallbackBase ()
Ptr< CallbackImplBase >	GetImpl () const

Private Member Functions
template<std::size_t... INDEX, typename... BoundArgs>
auto	BindImpl (std::index_sequence< INDEX... > seq, BoundArgs &&... bargs)
	Implementation of the Bind method.
bool	DoCheckType (Ptr< const CallbackImplBase > other) const
	Check for compatible types.
CallbackImpl< R, UArgs... > *	DoPeekImpl () const

Friends
template<typename ROther, typename... UArgsOther>
class	Callback

Additional Inherited Members
Protected Member Functions inherited from ns3::CallbackBase
	CallbackBase (Ptr< CallbackImplBase > impl)
	Construct from a pimpl.
Protected Attributes inherited from ns3::CallbackBase
Ptr< CallbackImplBase >	m_impl
	the pimpl

Detailed Description

template<typename R, typename... UArgs>
class ns3::Callback< R, UArgs >

Callback template class.

This class template implements the Functor Design Pattern. It is used to declare the type of a Callback:

• the first non-optional template argument represents the return type of the callback.
• the remaining (optional) template arguments represent the type of the subsequent arguments to the callback.

Callback instances are built with the MakeCallback template functions. Callback instances have POD semantics: the memory they allocate is managed automatically, without user intervention which allows you to pass around Callback instances by value.

Sample code which shows how to use this class template as well as the function templates MakeCallback :

/*
 * Copyright (c) 2006 INRIA
 *
 * SPDX-License-Identifier: GPL-2.0-only
 *
 */
 
#include "ns3/assert.h"
#include "ns3/callback.h"
#include "ns3/command-line.h"
 
#include <iostream>
 
/**
 * @file
 * @ingroup core-examples
 * @ingroup callback
 * Example program illustrating use of callback functions and methods.
 *
 * See \ref callback
 */
 
using namespace ns3;
 
namespace
{
 
/**
 * Example Callback function.
 *
 * @param [in] a The first argument.
 * @param [in] b The second argument.
 * @returns The first argument.
 */
double
CbOne(double a, double b)
{
    std::cout << "invoke cbOne a=" << a << ", b=" << b << std::endl;
    return a;
}
 
/** Example Callback class. */
class MyCb
{
  public:
    /**
     * Example Callback class method.
     *
     * @param [in] a The argument.
     * @returns -5
     */
    int CbTwo(double a)
    {
        std::cout << "invoke cbTwo a=" << a << std::endl;
        return -5;
    }
};
 
} // unnamed namespace
 
int
main(int argc, char* argv[])
{
    CommandLine cmd(__FILE__);
    cmd.Parse(argc, argv);
 
    // return type: double
    // first arg type: double
    // second arg type: double
    Callback<double, double, double> one;
    // build callback instance which points to cbOne function
    one = MakeCallback(&CbOne);
    // this is not a null callback
    NS_ASSERT(!one.IsNull());
    // invoke cbOne function through callback instance
    double retOne;
    retOne = one(10.0, 20.0);
    // callback returned expected value
    NS_ASSERT(retOne == 10.0);
 
    // return type: int
    // first arg type: double
    Callback<int, double> two;
    MyCb cb;
    // build callback instance which points to MyCb::cbTwo
    two = MakeCallback(&MyCb::CbTwo, &cb);
    // this is not a null callback
    NS_ASSERT(!two.IsNull());
    // invoke MyCb::cbTwo through callback instance
    int retTwo;
    retTwo = two(10.0);
    // callback returned expected value
    NS_ASSERT(retTwo == -5);
 
    two = MakeNullCallback<int, double>();
    // invoking a null callback is just like
    // invoking a null function pointer:
    // it will crash.
    // int retTwoNull = two (20.0);
    NS_ASSERT(two.IsNull());
 
#if 0
  // The below type mismatch between CbOne() and callback two will fail to
  // compile if enabled in this program.
  two = MakeCallback (&CbOne);
#endif
 
#if 0
  // This is a slightly different example, in which the code will compile
  // but because callbacks are type-safe, will cause a fatal error at runtime
  // (the difference here is that Assign() is called instead of operator=)
  Callback<void, float> three;
  three.Assign (MakeCallback (&CbOne));
#endif
 
    return 0;
}

Internal:

This code was originally written based on the techniques described in http://www.codeproject.com/cpp/TTLFunction.asp It was subsequently rewritten to follow the architecture outlined in "Modern C++ Design" by Andrei Alexandrescu in chapter 5, "Generalized Functors".

This code uses:

• default template parameters to saves users from having to specify empty parameters when the number of parameters is smaller than the maximum supported number
• the pimpl idiom: the Callback class is passed around by value and delegates the crux of the work to its pimpl pointer.
• a reference list implementation to implement the Callback's value semantics.

This code most notably departs from the alexandrescu implementation in that it does not use type lists to specify and pass around the types of the callback arguments. Of course, it also does not use copy-destruction semantics and relies on a reference list rather than autoPtr to hold the pointer.

See also

attribute_Callback

Template Parameters

R	[explicit] The return type of the Callback.
UArgs	[explicit] The types of any arguments to the Callback.

Definition at line 421 of file callback.h.

Constructor & Destructor Documentation

Callback() [1/4]

template<typename R, typename... UArgs>

template ns3::Callback< R, UArgs >::Callback ( )

inline

Definition at line 427 of file callback.h.

Callback() [2/4]

template<typename R, typename... UArgs>

ns3::Callback< R, UArgs >::Callback ( const Ptr< CallbackImpl< R, UArgs... > > & impl )

inline

Construct from a CallbackImpl pointer.

Parameters

[in]

impl

The CallbackImpl Ptr

Definition at line 436 of file callback.h.

Callback() [3/4]

template<typename R, typename... UArgs>

template<typename... BArgs>

ns3::Callback< R, UArgs >::Callback ( const Callback< R, BArgs..., UArgs... > & cb, BArgs... bargs )

inline

Construct from another callback and bind some arguments (if any)

Template Parameters

BArgs

[deduced] The types of the bound arguments

Parameters

[in]	cb	The existing callback
[in]	bargs	The values of the bound arguments

Definition at line 449 of file callback.h.

Callback() [4/4]

template<typename R, typename... UArgs>

template<typename T, typename... BArgs, std::enable_if_t<!std::is_base_of_v< CallbackBase, T > &&std::is_invocable_r_v< R, T, BArgs..., UArgs... >, int > = 0>

ns3::Callback< R, UArgs >::Callback ( T func, BArgs... bargs )

inline

Construct from a function and bind some arguments (if any)

Template Parameters

T	[deduced] The type of the function
BArgs	[deduced] The types of the bound arguments

Parameters

[in]	func	The function
[in]	bargs	The values of the bound arguments

Internal:

We leverage SFINAE to have the compiler discard this constructor when the type of the first argument is a class derived from CallbackBase (i.e., a Callback).

Definition at line 481 of file callback.h.

Member Function Documentation

Assign()

template<typename R, typename... UArgs>

bool ns3::Callback< R, UArgs >::Assign ( const CallbackBase & other )

inline

Adopt the other's implementation, if type compatible.

Parameters

[in]

other

Callback

Returns

true if other was type-compatible and could be adopted.

Definition at line 605 of file callback.h.

Bind()

template<typename R, typename... UArgs>

template<typename... BoundArgs>

auto ns3::Callback< R, UArgs >::Bind ( BoundArgs &&... bargs )

inline

Bind a variable number of arguments.

Template Parameters

BoundArgs

[deduced] The types of the arguments to bind

Parameters

[in]

bargs

The values of the arguments to bind

Returns

The bound callback

Definition at line 543 of file callback.h.

Referenced by ns3::TracedCallback< Ts >::Connect(), ns3::TracedCallback< Ts >::Disconnect(), CallbackEqualityTestCase::DoRun(), and ns3::QosTxop::SetDroppedMpduCallback().

Here is the caller graph for this function:

BindImpl()

template<typename R, typename... UArgs>

template<std::size_t... INDEX, typename... BoundArgs>

auto ns3::Callback< R, UArgs >::BindImpl ( std::index_sequence< INDEX... > seq, BoundArgs &&... bargs )

inlineprivate

Implementation of the Bind method.

Template Parameters

BoundArgs

The types of the arguments to bind

Parameters

[in]	seq	A compile-time integer sequence
[in]	bargs	The values of the arguments to bind

Returns

The bound callback

Internal:

The integer sequence is 0..N-1, where N is the number of arguments left unbound.

Definition at line 515 of file callback.h.

Referenced by ns3::Callback< void, int >::Bind().

Here is the caller graph for this function:

CheckType()

template<typename R, typename... UArgs>

bool ns3::Callback< R, UArgs >::CheckType ( const CallbackBase & other ) const

inline

Check for compatible types.

Parameters

[in]

other

Callback Ptr

Returns

true if other can be dynamic_cast to my type

Definition at line 594 of file callback.h.

DoCheckType()

template<typename R, typename... UArgs>

bool ns3::Callback< R, UArgs >::DoCheckType ( Ptr< const CallbackImplBase > other ) const

inlineprivate

Check for compatible types.

Parameters

[in]

other

Callback Ptr

Returns

true if other can be dynamic_cast to my type

Definition at line 635 of file callback.h.

Referenced by ns3::Callback< void, int >::Assign(), and ns3::Callback< void, int >::CheckType().

Here is the caller graph for this function:

DoPeekImpl()

template<typename R, typename... UArgs>

CallbackImpl< R, UArgs... > * ns3::Callback< R, UArgs >::DoPeekImpl ( ) const

inlineprivate

Returns

The pimpl pointer

Definition at line 624 of file callback.h.

Referenced by ns3::Callback< void, int >::Callback(), ns3::Callback< void, int >::BindImpl(), ns3::Callback< void, int >::IsNull(), and ns3::Callback< void, int >::operator()().

Here is the caller graph for this function:

IsEqual()

template<typename R, typename... UArgs>

bool ns3::Callback< R, UArgs >::IsEqual ( const CallbackBase & other ) const

inline

Equality test.

Parameters

[in]

other

Callback

Returns

true if we are equal

Definition at line 583 of file callback.h.

Referenced by CallbackEqualityTestCase::DoRun(), ns3::aodv::QueueEntryTest::DoRun(), and ns3::operator!=().

Here is the caller graph for this function:

IsNull()

template<typename R, typename... UArgs>

bool ns3::Callback< R, UArgs >::IsNull ( ) const

inline

Check for null implementation.

Returns

true if I don't have an implementation

Definition at line 555 of file callback.h.

Referenced by ns3::TcpTxBuffer::DiscardUpTo(), NullifyCallbackTestCase::DoRun(), ns3::WifiMode::GetNonHtReferenceRate(), ns3::Packet::Print(), ns3::Packet::PrintByteTags(), ns3::Packet::PrintPacketTags(), ns3::aodv::RoutingProtocol::RouteInput(), ns3::dsdv::RoutingProtocol::RouteInput(), ns3::Ipv4GlobalRouting::RouteInput(), ns3::Ipv4StaticRouting::RouteInput(), ns3::Ipv6StaticRouting::RouteInput(), ns3::NixVectorRouting< T >::RouteInput(), ns3::olsr::RoutingProtocol::RouteInput(), ns3::Rip::RouteInput(), ns3::RipNg::RouteInput(), ns3::TcpSocketMsgBase::SetAfterRetransmitCb(), ns3::TcpSocketMsgBase::SetBeforeRetransmitCb(), ns3::lorawan::LoraRadioEnergyModelPhyListener::SetChangeStateCallback(), ns3::WifiRadioEnergyModelPhyListener::SetChangeStateCallback(), ns3::AcousticModemEnergyModel::SetEnergyDepletionCallback(), ns3::lorawan::LoraRadioEnergyModel::SetEnergyDepletionCallback(), ns3::WifiRadioEnergyModel::SetEnergyDepletionCallback(), ns3::AcousticModemEnergyModel::SetEnergyRechargeCallback(), ns3::lorawan::LoraRadioEnergyModel::SetEnergyRechargedCallback(), ns3::WifiRadioEnergyModel::SetEnergyRechargedCallback(), TcpSocketAdvertisedWindowProxy::SetInvalidAwndCb(), ns3::TcpSocketMsgBase::SetProcessedAckCb(), ns3::TcpSocketMsgBase::SetRcvAckCb(), ns3::TcpSocketMsgBase::SetUpdateRttHistoryCb(), ns3::lorawan::LoraRadioEnergyModelPhyListener::SetUpdateTxCurrentCallback(), ns3::WifiRadioEnergyModelPhyListener::SetUpdateTxCurrentCallback(), and ns3::TcpTxBuffer::Update().

Here is the caller graph for this function:

Nullify()

template<typename R, typename... UArgs>

void ns3::Callback< R, UArgs >::Nullify ( )

inline

Discard the implementation, set it to null.

Definition at line 561 of file callback.h.

Referenced by NullifyCallbackTestCase::DoRun().

Here is the caller graph for this function:

operator()()

template<typename R, typename... UArgs>

R ns3::Callback< R, UArgs >::operator() ( UArgs... uargs ) const

inline

Functor with varying numbers of arguments.

Parameters

uargs

The arguments to the callback

Returns

Callback value

Definition at line 572 of file callback.h.

Friends And Related Symbol Documentation

Callback

template<typename R, typename... UArgs>

template<typename ROther, typename... UArgsOther>

friend class Callback

friend

Definition at line 424 of file callback.h.

---

The documentation for this class was generated from the following files:

• src/core/model/callback.h
• src/core/model/object-base.cc
• src/core/model/object-base.h