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,
			y
	)

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

x	the position (starting from 1) of the format string argument
y	the 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.