Class Visibility and Exposure

Kratos Class Visibility and Exposure

Kratos framework is mainly divided into "Core" and "Application" layers. The "Core" layer will provide functionality while Interfaces, Wrappers, and other Cores will consume it.

In order provide access to its classes and functions correctly, there are some guidelines that you must follow while implementing components inside a Core.

KRATOS_API

In order to ease the resolution of visibility of your symbols, Kratos provides the KRATOS_API(<APPLICATION_NAME>) which you can (and must) use when you are creating a source file containing the implementation of a class you intend to be usable outside the Core layer.

// custom_example.h
class KRATOS_API(CUSTOM_APP) CustomExample 
{
    CustomExample();
    ~CustomExample();
    ...
}

// custom_example.cpp
CustomExample::CustomExample()
{
    ...
}

CustomExample::~CustomExample()
{
    ...
}

Exposure

We understand by exposure the degree of functionality that you intend to make public to other users to use, modify and extend your classes. We distinguish several scenarios which will govern how your classes must be implemented:

• Private classes
• Public classes with no templates
• Public classes with templates
  • Final, No Specialized
  • Final, Specialized
  • Derivable, No Specialized
  • Derivable, Specialized

Private classes

We understand by private classes the ones that are not meant to be used outside the same compilation unit. You can do mostly anything you want:

• Must be split into source and header.
• No need to use KRATOS_API
• Can freely use templates in any fashion.

Example:

// private_example.h
class PrivateExample 
{
    PrivateExample();
    ~PrivateExample();
    ...
}

// private_example.cpp
PrivateExample::PrivateExample()
{
    ...
}

PrivateExample::~PrivateExample()
{
    ...
}

Public classes with no templates

We understand by public class the ones that are meant to be usable outside the same compilation unit. For example, a process or a utility.

• Must not contain templates.
• Must be split into source and header.
• Need to use KRATOS_API in the header only (se example)
• Can be final or not.

Example:

// public_example.h
class KRATOS_API(PUBLIC_CLASS) PublicExample 
{
    PublicExample();
    ~PublicExample();
    ...
}

// public_example.cpp
PublicExample::PublicExample()
{
    ...
}

PublicExample::~PublicExample()
{
    ...
}

Public classes with templates

We understand by Public template classes the ones that are meant to be usable outside the same compilation unit and use templates.

Inside this category we will make several distinctions, mostly depending on how this classes are going to be instantiated and derived.

Final, No Specialized

If your class is Final (impossible to derive) and No Specialized (you will do the same for all instance parameters)

• Must be split into source and header.
• Must be explicitly instantiated with all instances you intend to make public
• Need to use KRATOS_API in the header only (se example)
• Must be marked with the final keyword to avoid confusion

Example:

// public_example.h
temaplte<class TData>
class final KRATOS_API(PUBLIC_CLASS) PublicExample 
{
    PublicExample();
    ~PublicExample();
    ...
}

// public_example.cpp
teamplate<class TData>
PublicExample<TData>::PublicExample()
{
    ...
}

teamplate<class TData>
PublicExample<TData>::~PublicExample()
{
    ...
}

// All types must be exposed here
template class PublicExample<int>
template class PublicExample<double>

Final, Specialized

We strongly suggest not to use this combination. Please consider if constexpr instead.

Derivable, No Specialized

If your class is non Final (derivable) and No Specialized (you will do the same for all instance parameters)

• Must be header only
• Must not use KRATOS_API in any case.

Example:

// public_example.h
temaplte<class TData>
class final PublicExample 
{
    PublicExample() 
    {
        ...
    };

    ~PublicExample() 
    {
        ...
    };
}

Derivable, Specialized

We strongly suggest not to use this combination. Please consider if constexpr instead.