Skip to content
v1.11dev
GitHub

Guides

Move from the FairMQ* names

The API of FairMQ is in the namespace fair::mq, and its headers are in the directory fairmq/. The old global names like FairMQDevice and the old headers like <FairMQDevice.h> still compile, but the compiler warns. This guide moves your code to the new names and lists each old name with its replacement.

Before and after

Section titled “Before and after”
mydevice.cxx (old)
#include <FairMQDevice.h>


class MyDevice : public FairMQDevice
{
    bool HandleData(FairMQMessagePtr& msg, int);
};
mydevice.cxx (new)
#include <fairmq/Device.h>


class MyDevice : public fair::mq::Device
{
    bool HandleData(fair::mq::MessagePtr& msg, int);
};

Move your code

Section titled “Move your code”

  1. Replace the old #include lines. Use the table Headers.

  2. Replace the old type names. Use the table Type names. fairmq-tidy finds most of them for you.

  3. If your main() comes from runFairMQDevice.h, move to runDevice.h. See Replace runFairMQDevice.h.

  4. Replace the deprecated functions and members. Use the table Functions and members.

  5. Build with -Werror=deprecated-declarations. The compiler then stops at each remaining use of a deprecated name:

    Terminal window
    cmake -S . -B build -DCMAKE_CXX_FLAGS="-Werror=deprecated-declarations"
    cmake --build build

How the compiler warns

Section titled “How the compiler warns”

An old header contains a #pragma GCC warning. An old type name or member has the attribute [[deprecated("…")]], and the compiler prints the text of the attribute. For the old code above, GCC and Clang print these warnings (the paths are shorter here):

FairMQDevice.h:13:21: warning: Deprecated header: Use <fairmq/Device.h> instead
mydevice.cxx:5:47: warning: 'using FairMQMessagePtr = using fair::mq::MessagePtr = class std::unique_ptr<fair::mq::Message>' is deprecated: Use fair::mq::MessagePtr [-Wdeprecated-declarations]

The compiler does not show all uses:

  • GCC 13 does not warn for a deprecated alias in a list of base classes, for example class MyDevice : public FairMQDevice. Clang and fairmq-tidy find it.
  • <fairmq/FwdDecls.h> declares twelve of the old names again, without the attribute. A file that includes only this header gets no warning for these names.
  • An old header warns only if the file did not include the new header before. FairMQLogger.h always warns. runFairMQDevice.h does not warn.
  • FairMQDevicePtr of runFairMQDevice.h has no attribute.

Headers

Section titled “Headers”

Each old header includes the new header, so the old #include lines still work. The include directories of an installed FairMQ::FairMQ are include and include/fairmq, so the old headers also work with the prefix fairmq/, for example <fairmq/FairMQDevice.h>.

Old header New header Warning
<FairMQChannel.h> <fairmq/Channel.h> yes
<FairMQDevice.h> <fairmq/Device.h> yes
<FairMQLogger.h> <fairlogger/Logger.h> (FairLogger) yes, always
<FairMQMessage.h> <fairmq/Message.h> yes
<FairMQParts.h> <fairmq/Parts.h> yes
<FairMQPoller.h> <fairmq/Poller.h> yes
<FairMQSocket.h> <fairmq/Socket.h> yes
<FairMQTransportFactory.h> <fairmq/TransportFactory.h> yes
<FairMQUnmanagedRegion.h> <fairmq/UnmanagedRegion.h> yes
<options/FairMQProgOptions.h> <fairmq/ProgOptions.h> yes
<runFairMQDevice.h> <fairmq/runDevice.h> no

Type names

Section titled “Type names”

The table is in the order of the headers that declare the deprecated alias. The column fairmq-tidy shows if the check finds the name (with Clang 18).

Old name New name Declared in fairmq-tidy
FairMQChannel fair::mq::Channel Channel.h yes
FairMQChannelMap fair::mq::ChannelMap Device.h yes
InputMsgCallback fair::mq::InputMsgCallback Device.h no
InputMultipartCallback fair::mq::InputMultipartCallback Device.h no
FairMQDevice fair::mq::Device Device.h yes
fair::mq::FairMQMemoryResource fair::mq::MemoryResource MemoryResources.h no
fairmq_free_fn fair::mq::FreeFn Message.h no
FairMQMessage fair::mq::Message Message.h yes
FairMQMessagePtr fair::mq::MessagePtr Message.h yes
FairMQParts fair::mq::Parts Parts.h yes
FairMQPoller fair::mq::Poller Poller.h yes
FairMQPollerPtr fair::mq::PollerPtr Poller.h yes
FairMQProgOptions fair::mq::ProgOptions ProgOptionsFwd.h yes
FairMQSocket fair::mq::Socket Socket.h yes
FairMQSocketPtr fair::mq::SocketPtr Socket.h yes
FairMQTransportFactory fair::mq::TransportFactory TransportFactory.h yes
FairMQTransportFactoryError fair::mq::TransportFactoryError TransportFactory.h yes
FairMQRegionEvent fair::mq::RegionEvent UnmanagedRegion.h yes
FairMQRegionInfo fair::mq::RegionInfo UnmanagedRegion.h yes
FairMQRegionBlock fair::mq::RegionBlock UnmanagedRegion.h yes
FairMQRegionCallback fair::mq::RegionCallback UnmanagedRegion.h yes
FairMQRegionBulkCallback fair::mq::RegionBulkCallback UnmanagedRegion.h yes
FairMQRegionEventCallback fair::mq::RegionEventCallback UnmanagedRegion.h yes
FairMQUnmanagedRegion fair::mq::UnmanagedRegion UnmanagedRegion.h yes
FairMQUnmanagedRegionPtr fair::mq::UnmanagedRegionPtr UnmanagedRegion.h yes
FairMQRegionConfig fair::mq::RegionConfig UnmanagedRegion.h yes
FairMQDevicePtr std::unique_ptr<fair::mq::Device> as the return type of getDevice() runFairMQDevice.h yes, as fair::mq::Device *

All old names are global, except fair::mq::FairMQMemoryResource. All names in the table except FairMQDevicePtr have the attribute [[deprecated]].

Replace runFairMQDevice.h

Section titled “Replace runFairMQDevice.h”

runFairMQDevice.h and runDevice.h both contain a main() function. Your code gives the two functions getDevice() and addCustomOptions(). The signature of getDevice() is different:

Header Declaration of getDevice()
runFairMQDevice.h FairMQDevicePtr getDevice(const fair::mq::ProgOptions& config); with FairMQDevicePtr = fair::mq::Device*
runDevice.h std::unique_ptr<fair::mq::Device> getDevice(fair::mq::ProgOptions& config);

addCustomOptions(boost::program_options::options_description&) is the same in both headers.

Old code
#include <runFairMQDevice.h>


FairMQDevicePtr getDevice(const fair::mq::ProgOptions& /*config*/)
{
    return new MyDevice();
}

The new code returns a std::unique_ptr, and the parameter is not const. The example 1-1 uses the new header:

examples/1-1/sampler.cxx
#include <fairmq/Device.h>
#include <fairmq/runDevice.h>
examples/1-1/sampler.cxx:9–10
examples/1-1/sampler.cxx
std::unique_ptr<fair::mq::Device> getDevice(fair::mq::ProgOptions& /*config*/)
{
    return std::make_unique<Sampler>();
}
examples/1-1/sampler.cxx:66–69

Functions and members

Section titled “Functions and members”

The compiler warns for these members too. The column "Declared in" names the header in fairmq/.

Old New Declared in
Device::fChannels GetChannels() Device.h
Device::GetStateName(state) fair::mq::GetStateName(state) of <fairmq/States.h> Device.h
Device::GetTransitionName(transition) fair::mq::GetTransitionName(transition) of <fairmq/States.h> Device.h
Device::Serialize<S>(msg, data, args...) S().Serialize(msg, data, args...) Device.h
Device::Deserialize<D>(msg, data, args...) D().Deserialize(msg, data, args...) Device.h
Parts::AddPart(Message* msg) Parts::AddPart(MessagePtr msg) Parts.h
Parts::AtRef(index) *(parts.At(index)) with At() Parts.h
Socket::Close() Destroy the socket. Its destructor closes it. Socket.h
shmem::Socket::GetConstant() and zmq::Socket::GetConstant() fair::mq::zmq::getConstant() of <fairmq/zeromq/Common.h> shmem/Socket.h, zeromq/Socket.h

CMake names

Section titled “CMake names”

The CMake package is FairMQ. Link your targets with FairMQ::FairMQ. The executables of FairMQ are imported targets with the same prefix, for example FairMQ::fairmq-bsampler. See Use FairMQ in a CMake project.

Automate the search with fairmq-tidy

Section titled “Automate the search with fairmq-tidy”

fairmq-tidy finds the uses of most old type names and shows the new name for each one. It does not look at the #include lines and the members, and it does not change your files. See Check code with fairmq-tidy.

Section titled “Related pages”