FairMQ/fairmq/devices

Introduction

The Tutorial 7 show how to use three generic devices, namely a generic sampler, processor and filesink. These three devices are policy based designed classes. These devices all inherit from FairMQDevice and from specific template parameters, namely :

• The sampler inherit from
• a sampler policy (e.g a file reader)
• an output policy (serialize)
• The processor inherit from
• an input policy (deserialize)
• an output policy (serialize)
• a task policy (process data)
• The filesink inherit from
• an input policy (deserialize)
• a storage policy.

Some policy examples (c.f. e.g. BoostSerializer.h) are available in FairRoot/Base/MQ. In this design the user only need to implement the policies, which are, depending on the devices, the serialization/deserialization tasks, the process tasks, the source and the sink implementations. The message queue implementation are provided by the host class, and do not need to be provided by the users.

Generic devices

The generic devices are part of the FairMQ library, and can be found in the FairRoot/fairmq/devices directory. These generic devices are called host classes and publicly inherit from template parameters called policies.

Generic Sampler

In the example of the GenericSampler.h, the beginning of the header look like :

// in GenericSampler.h
template <typename T, typename U, typename K, typename L>
class base_GenericSampler : public FairMQDevice, public T, public U
{
    typedef T source_type;
    typedef U serialization_type;
    // etc...
};

The host template class base_GenericSampler has four template parameters, i.e. T, U, K, L. The parameter T and U correspond to the source policy and serialization policy, respectively.

The template parameters K and L are used to define the key and function type of a task container (std::map<K,L>). For the moment, only L=std::function<void()> is supported by the base_GenericSampler host class. The task map mechanism is an experimental feature and might be replaced with boost::signal2. The users do not need to use directly the base_GenericSampler, and define the K and L parameter types. Instead an alias template, GenericSampler, that take two template parameters (source and serialization policies) is defined at the end of the implementation file (GenericSampler.tpl).

// in GenericSampler.tpl
// base_GenericSampler implementation ...

// alias template for the policies. K and L types have default values.
template<typename T, typename U>
using GenericSampler = base_GenericSampler<T,U,int,std::function<void()>>;

Sampler policies

The policies must have at least a couple of methods that will be called by the host class. For example all policies must have default constructor. In addition some functions are required and other are enabled only if the function signatures exist in the policy classes.

Input policy (Source)

				source_type::InitSampler() 						// must be there to compile
int64_t 		source_type::GetNumberOfEvent() 				// must be there to compile

				source_type::SetIndex(int64_t eventIdx)			// must be there to compile
CONTAINER_TYPE  source_type::GetOutData() 						// must be there to compile

				source_type::SetFileProperties(Args&... args) 	// if called then must be there to compile
				source_type::ExecuteTasks()						// must be there to compile

 void 			source_type::BindSendPart(std::function<void(int)> callback)		// enabled if exists
 void 			source_type::BindGetSocketNumber(std::function<int()> callback) 	// enabled if exists
 void 			source_type::BindGetCurrentIndex(std::function<int()> callback)		// enabled if exists

The function members above that have no returned type means that the returned types are not used and can be anything. The CONTAINER_TYPE above must correspond to the input parameter of the serialization_type::SerializeMsg() function (see below).

Output policy (Serialization)

		serialization_type::SerializeMsg(CONTAINER_TYPE container)	// must be there to compile
		serialization_type::SetMessage(FairMQMessage* msg) 			// must be there to compile

Examples of host class instantiation can be found in FairRoot/example/Tutorial7/run directory. For example