VLC 4.0.0-dev
Loading...
Searching...
No Matches
C programming language extensions

This section defines a number of macros and inline functions extending the C language. More...

Collaboration diagram for C programming language extensions:

Modules

 Error codes
 
 Integer operations
 Common integer functions.
 
 Linked lists
 
 Linked lists (C++ wrappers)
 
 In-memory byte streams
 In-memory byte stream are a portable wrapper for in-memory formatted output byte streams.
 
 Thread-safe queues (FIFO)
 
 String helpers
 
 Vector
 

Macros

#define VLC_USED
 
#define VLC_MALLOC
 
#define VLC_DEPRECATED
 
#define VLC_DEPRECATED_ENUM
 Deprecated enum member annotation.
 
#define VLC_FORMAT(x, y)
 String format function annotation.
 
#define VLC_FORMAT_ARG(x)
 Format string translation function annotation.
 
#define VLC_WEAK
 Weak symbol annotation.
 
#define likely(p)   (!!(p))
 Predicted true condition.
 
#define unlikely(p)   (!!(p))
 Predicted false condition.
 
#define unreachable()   ((void)0)
 Impossible branch.
 
#define vlc_assert_unreachable()   (vlc_assert(!"unreachable"), unreachable())
 Impossible branch assertion.
 
#define vlc_assert(pred)   ((void)0)
 Run-time assertion.
 
#define VLC_EXTERN
 
#define VLC_EXPORT
 
#define VLC_API   VLC_EXTERN VLC_EXPORT
 Exported API call annotation.
 

Detailed Description

This section defines a number of macros and inline functions extending the C language.

Most extensions are implemented by GCC and LLVM/Clang, and have unoptimized fallbacks for other C11/C++11 conforming compilers.

Macro Definition Documentation

◆ likely

#define likely (   p)    (!!(p))

Predicted true condition.

This macro indicates that the condition is expected most often true. The compiler may optimize the code assuming that this condition is usually met.

◆ unlikely

#define unlikely (   p)    (!!(p))

Predicted false condition.

This macro indicates that the condition is expected most often false. The compiler may optimize the code assuming that this condition is rarely met.

◆ unreachable

#define unreachable ( )    ((void)0)

Impossible branch.

This macro indicates that the branch cannot be reached at run-time, and represents undefined behaviour. The compiler may optimize the code assuming that the call flow will never logically reach the point where this macro is expanded.

See also vlc_assert_unreachable.

◆ VLC_API

#define VLC_API   VLC_EXTERN VLC_EXPORT

Exported API call annotation.

This macro is placed before a function declaration to indicate that the function is an API call of the LibVLC plugin API.

◆ vlc_assert

#define vlc_assert (   pred)    ((void)0)

Run-time assertion.

This macro performs a run-time assertion if C assertions are enabled and the following preprocessor symbol is defined:

LIBVLC_INTERNAL_ 

That restriction ensures that assertions in public header files are not unwittingly leaked to externally-compiled plug-ins including those header files.

Within the LibVLC code base, this is exactly the same as assert(), which can and probably should be used directly instead.

◆ vlc_assert_unreachable

#define vlc_assert_unreachable ( )    (vlc_assert(!"unreachable"), unreachable())

Impossible branch assertion.

This macro asserts that the branch cannot be reached at run-time.

If the branch is reached in a debug build, it will trigger an assertion failure and abnormal program termination.

If the branch is reached in a non-debug build, this macro is equivalent to unreachable and the behaviour is undefined.

◆ VLC_DEPRECATED

#define VLC_DEPRECATED

◆ VLC_DEPRECATED_ENUM

#define VLC_DEPRECATED_ENUM

Deprecated enum member annotation.

Use this macro after an enumerated type member declaration. The compiler may emit a warning every time the enumeration member is used.

See also VLC_DEPRECATED.

◆ VLC_EXPORT

#define VLC_EXPORT

◆ VLC_EXTERN

#define VLC_EXTERN

◆ VLC_FORMAT

#define VLC_FORMAT (   x,
 
)

String format function annotation.

Use this macro after a function prototype/declaration if the function expects a standard C format string. This helps compiler diagnostics.

Parameters
xthe position (starting from 1) of the format string argument
ythe first position (also starting from 1) of the variable arguments following the format string (usually but not always x+1).

◆ VLC_FORMAT_ARG

#define VLC_FORMAT_ARG (   x)

Format string translation function annotation.

Use this macro after a function prototype/declaration if the function expects a format string as input and returns another format string as output to another function.

This is primarily intended for localization functions such as gettext().

◆ VLC_MALLOC

#define VLC_MALLOC

◆ VLC_USED

#define VLC_USED

◆ VLC_WEAK

#define VLC_WEAK

Weak symbol annotation.

Use this macro before an external identifier definition to mark it as a weak symbol. A weak symbol can be overridden by another symbol of the same name at the link time.