SoftBank Robotics documentation What's new in NAOqi 2.8?

qi helper macros

Reference

QI_API_DEPRECATED
QI_NORETURN

Portable noreturn attribute, used to declare that a function does not return.

QI_HAS_VARIABLE_LENGTH_ARRAY

Mark compilers supporting variable length array (VLA)

QI_LIB_API
QI_IMPORT_API
QI_EXPORT_API
QI_LIB_API_NORMALIZED
QI_COMPILER_WARNING(x)

x

The string displayed as the warning.

QI_DEPRECATED_HEADER(x)

Generate a compiler warning stating a header is deprecated. add a message to explain what user should do.

QI_DEPRECATE_MACRO(name)

name

The name of the macro. * Example: * * .. code-block:: cpp * * #define MAX(x,y)(QI_DEPRECATE_MACRO(MAX), x > y ? x : y) *

QI_DISALLOW_COPY_AND_ASSIGN(type)

DeprecatedUse boost::noncopyable instead.

Example:

class Foo : private boost::nonpyable
{};

type

The class name of which we want to forbid copy.

Note

This macro should always be in the private (or protected) section of a class.

Example:

class Foo {
    Foo();
private:
    QI_DISALLOW_COPY_AND_ASSIGN(Foo);
};
QI_WARN_UNUSED_RESULT

This macro tags a result as unused.

QI_ATTR_UNUSED

This macro tags a attribute as unused.

QI_UNUSED(x)

Example:

int zero(int QI_UNUSED(x))
{
  return 0;
}
QI_UNIQ_DEF(A)

A macro to append the line number of the parent macro usage, to define a function in or a variable and avoid name collision.

QI_CXX11_ENABLED
QI_NOEXCEPT(cond)

Specify that a function may throw or not. Do nothing if noexcept is not available.

QI_ONCE(code)
void myFunction()
{
  QI_ONCE(std::cout << "first initialization" << std::endl);
  std::cout << "doing stuff" << std::endl;
}

In this code, you have two guarantees: - “first initialization” will be written only once - “doing stuff” will never appear before “first initialization”

QI_ONCE is optimized so that further calls after initialization have the less overhead possible.

You can also put multiple instructions in a QI_ONCE.

QI_ONCE(
    doStuff();
    doMoreStuff();
    );

This macro is only useful in C++03 and the function above may be written in C++11:

void myFunction()
{
  static std::once_flag flag;
  std::call_once(flag,
      [](){std::cout << "first initialization" << std::endl;});
  std::cout << "doing stuff" << std::endl;
}
QI_THREADSAFE_NEW(...)

Accept a list of pointers (expected to be static function variables) and new them once in a thread-safe manner. Implementation aims for minimal overhead when initialization is done.

QI_THREADSAFE_NEW is there to provide a safe static initialization of variables in C++03. Its most common use case is the following:

static std::vector<int> vec;

void threadSafeFunction()
{
  static boost::mutex* mutex; // = 0 is optional
  QI_THREADSAFE_NEW(mutex);
  boost::mutex::scoped_lock l(*mutex);
  vec.push_back(0);
}

Using a simple static boost::mutex does not guarantee safe initialization in a multithreaded environment in C++03 (even though GCC’s implementation is safe), that’s why QI_THREADSAFE_NEW is needed.

In C++11, the following is safe:

static std::vector<int> vec;

void threadSafeFunction()
{
  static boost::mutex mutex;
  boost::mutex::scoped_lock l(mutex);
  vec.push_back(0);
}