vtkAssume.h File Reference

Compiler hint macros for assumptions and branch prediction. More...

#include "vtkCompiler.h"
#include <cassert>

Include dependency graph for vtkAssume.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	VTK_ASSUME(cond)
	Assert a condition to the compiler as always true, aborting in debug builds if violated.
#define	VTK_ASSUME_NO_ASSERT(cond)
	Same optimizer hint as VTK_ASSUME but without the debug-mode assertion.
#define	VTK_HAS_BUILTIN(x)
#define	VTK_ASSUME_IMPL(cond)
#define	VTK_EXPECT(cond, expected)
	Low-level branch-prediction hint wrapping __builtin_expect.
#define	VTK_LIKELY(cond)
	Hint that cond is expected to be true most of the time.
#define	VTK_UNLIKELY(cond)
	Hint that cond is expected to be false most of the time.

Detailed Description

Compiler hint macros for assumptions and branch prediction.

This header provides four families of macros:

• VTK_ASSUME(cond) — tells the compiler cond is always true, with a debug-mode assert to catch violations at runtime.
• VTK_ASSUME_NO_ASSERT(cond) — same optimizer hint, but skips the assert.
• VTK_EXPECT(cond, expected) / VTK_LIKELY(cond) / VTK_UNLIKELY(cond) — branch-prediction hints that do not invoke undefined behaviour when wrong.

A more detailed description and related tools can be found here.

Definition in file vtkAssume.h.

Macro Definition Documentation

VTK_ASSUME

#define VTK_ASSUME

(

cond

)

Value:

  do                                                                                               \
  {                                                                                                \
    const bool c = cond;                                                                           \
    assert("Bad assumption in VTK_ASSUME: " #cond&& c);                                            \
    VTK_ASSUME_IMPL(c);                                                                            \
    (void)c;      /* Prevents unused var warnings */                                               \
  } while (false) /* do-while prevents extra semicolon warnings */

Assert a condition to the compiler as always true, aborting in debug builds if violated.

Instructs the compiler that cond will always evaluate to true at this point in the program, enabling additional optimizations that would otherwise be impossible. In debug builds (NDEBUG not defined) a standard assert fires if the condition is false, making violations easy to catch during development.

Warning: if cond is false in a release build the behaviour is undefined. Only use this macro for invariants you are completely certain about.

Common use-case — fixed component count on a typed array:

// Tell the compiler the array always has exactly 3 components so it can
// unroll the inner loop and use contiguous-stride memory access patterns.
VTK_ASSUME(array->GetNumberOfComponents() == 3);
for (vtkIdType tupleIdx = 0; tupleIdx < nTuples; ++tupleIdx)
{
  double x = array->GetTypedComponent(tupleIdx, 0);
  double y = array->GetTypedComponent(tupleIdx, 1);
  double z = array->GetTypedComponent(tupleIdx, 2);
  // ...
}

Use inside vtkArrayDispatch workers:

struct MyWorker
{
  template <typename ArrayT>
  void operator()(ArrayT* array)
  {
    // The dispatch already guarantees 3 components; tell the compiler too.
    VTK_ASSUME(array->GetNumberOfComponents() == 3);
    // ... optimized component access ...
  }
};

Parameters

cond	A boolean expression that must always be true at this point.

Definition at line 70 of file vtkAssume.h.

VTK_ASSUME_NO_ASSERT

#define VTK_ASSUME_NO_ASSERT

(

cond

)

Value:

  do                                                                                               \
  {                                                                                                \
    const bool c = cond;                                                                           \
    VTK_ASSUME_IMPL(c);                                                                            \
    (void)c;      /* Prevents unused var warnings */                                               \
  } while (false) /* do-while prevents extra semicolon warnings */

Same optimizer hint as VTK_ASSUME but without the debug-mode assertion.

Passes cond to the compiler as an always-true assumption for optimization purposes while deliberately omitting the assert. Use this variant when the condition is provably true by construction and the assertion would be noise, or in performance-critical inner loops where even the assert overhead in debug builds is undesirable.

Like VTK_ASSUME, a false condition in a release build is undefined behaviour.

// nComps is passed in from the caller which already validated it.
// Skip the redundant assert here.
VTK_ASSUME_NO_ASSERT(nComps > 0);
for (int c = 0; c < nComps; ++c) { ... }

Parameters

cond	A boolean expression that must always be true at this point.

Definition at line 101 of file vtkAssume.h.

VTK_HAS_BUILTIN

#define VTK_HAS_BUILTIN

(

x

)

Value:

0

Definition at line 112 of file vtkAssume.h.

VTK_ASSUME_IMPL

#define VTK_ASSUME_IMPL

(

cond

)

Value:

  do                                                                                               \
  {                                                                                                \
  } while (false) /* no-op */

Definition at line 127 of file vtkAssume.h.

VTK_EXPECT

#define VTK_EXPECT	(		cond,
			expected )

Value:

(cond)

Low-level branch-prediction hint wrapping __builtin_expect.

Tells the CPU/compiler that cond is expected to equal expected (0 or 1). Unlike VTK_ASSUME, a misprediction is safe — it only affects performance, not correctness. Prefer the higher-level VTK_LIKELY / VTK_UNLIKELY wrappers in most situations.

if (VTK_EXPECT(ptr != nullptr, 1)) // equivalent to VTK_LIKELY(ptr != nullptr)
{
  ptr->DoWork();
}

Parameters

cond	The condition to evaluate.
expected	The value (0 or 1) the compiler should assume cond takes.

Definition at line 199 of file vtkAssume.h.

VTK_LIKELY

#define VTK_LIKELY

(

cond

)

Value:

(cond)

Hint that cond is expected to be true most of the time.

Use this to improve branch-prediction on hot code paths where cond is almost always true. Has no effect on correctness.

if (VTK_LIKELY(array != nullptr))
{
  // Hot path — array is almost always valid.
  ProcessArray(array);
}
else
{
  // Cold path — rare error case.
  vtkErrorMacro("Array is null.");
}

Parameters

cond	The boolean expression expected to be true.

Definition at line 200 of file vtkAssume.h.

VTK_UNLIKELY

#define VTK_UNLIKELY

(

cond

)

Value:

(cond)

Hint that cond is expected to be false most of the time.

Use this on error-handling branches or rarely-taken code paths. Has no effect on correctness.

if (VTK_UNLIKELY(index < 0 || index >= size))
{
  vtkErrorMacro("Index " << index << " out of range [0, " << size << ").");
  return;
}
// Normal path continues here.

Parameters

cond	The boolean expression expected to be false.

Definition at line 201 of file vtkAssume.h.