Detailed Description

Provides a stable interface to clang's Thread Safety Annotations.

Macro Definition Documentation

◆ ARENE_TSA_ACQUIRE

#define ARENE_TSA_ACQUIRE ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(acquire_capability(__VA_ARGS__))

Annotates a function or method as acquiring exclusive access to the named capabilities before exit, without releasing them on exit.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#acquire-acquire-shared-release-release-shared-release-generic

Parameters

...	A comma-separated list of the names of members/variables which provide the capabilities to be acquired. If omitted, assumed to be `this` .

◆ ARENE_TSA_ACQUIRE_SHARED

#define ARENE_TSA_ACQUIRE_SHARED ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(acquire_shared_capability(__VA_ARGS__))

Annotates a function or method as acquiring shared access to the named capabilities before exit, without releasing them on exit.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#acquire-acquire-shared-release-release-shared-release-generic

Parameters

...	A comma-separated list of the names of members/variables which provide the capabilities to be acquired. If omitted, assumed to be `this` .

◆ ARENE_TSA_ASSERT_CAPABILITY

#define ARENE_TSA_ASSERT_CAPABILITY ( x )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(assert_capability(x))

Annotates a function or method as asserting that the calling thread holds exclusive access to the named capability, and would terminate the process if it is not held.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#assert-capability-and-assert-shared-capability

Parameters

x	The name of the member or variable that provides the needed capability

Postcondition: The analysis will assume the given capability is held after exit from the annotated function or method.

◆ ARENE_TSA_ASSERT_SHARED_CAPABILITY

#define ARENE_TSA_ASSERT_SHARED_CAPABILITY ( x )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(assert_shared_capability(x))

Annotates a function or method as asserting that the calling thread holds shared access to the named capability, and would terminate the process if it is not held.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#assert-capability-and-assert-shared-capability

Parameters

x	The name of the member or variable that provides the needed capability

Postcondition: The analysis will assume the given capability is held after exit from the annotated function or method.

◆ ARENE_TSA_CAPABILITY

#define ARENE_TSA_CAPABILITY ( x )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(capability(x))

Annotates a type as a "capability," which is a type that provides synchronization protection.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#capability-string

Parameters

x	The name of the type; used in generating error messages.

◆ ARENE_TSA_EXCLUDES

#define ARENE_TSA_EXCLUDES ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(locks_excluded(__VA_ARGS__))

Annotates a function or method as requiring the calling thread must not hold access to the named capabilities before entry.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#excludes

Parameters

...	A comma-separated list of the names of members/variables which provide the needed capabilities.

◆ ARENE_TSA_GUARDED_BY

#define ARENE_TSA_GUARDED_BY ( x )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(guarded_by(x))

Annotates a member as being guarded by a given capability.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#guarded-by-c-and-pt-guarded-by-c

Parameters

x	The name of the member which provides the capability that guards the annotated member

◆ ARENE_TSA_NO_THREAD_SAFETY_ANALYSIS

#define ARENE_TSA_NO_THREAD_SAFETY_ANALYSIS ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(no_thread_safety_analysis)

Annotates a function or method as explicitly excluded from thread safety analysis.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#no-thread-safety-analysis

Note: This should only be done in situations where a function is too complex for TSA to work correctly, due to the known limitations of TSA.

◆ ARENE_TSA_PT_GUARDED_BY

#define ARENE_TSA_PT_GUARDED_BY ( x )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(pt_guarded_by(x))

Annotates a member that is a (smart)pointer's pointed to content as being guarded by a given capability.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#guarded-by-c-and-pt-guarded-by-c

Parameters

x	The name of the member which provides the capability that guards the annotated pointer-member

Note: This does not mark the pointer value itself as requiring synchronization. Only dereferencing it.

◆ ARENE_TSA_RELEASE

#define ARENE_TSA_RELEASE ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(release_capability(__VA_ARGS__))

Annotates a function or method as releasing access to the named capabilities before exit. The calling thread must hold exclusive access to the named capabilities before entering.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#acquire-acquire-shared-release-release-shared-release-generic

Parameters

...	A comma-separated list of the names of members/variables which provide the capabilities to be released. If omitted, assumed to be `this` .

◆ ARENE_TSA_RELEASE_GENERIC

#define ARENE_TSA_RELEASE_GENERIC ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(release_generic_capability(__VA_ARGS__))

Annotates a function or method as releasing access to the named capabilities before exit. The calling thread can hold either exclusive or shared access to the named capabilities before entering.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#acquire-acquire-shared-release-release-shared-release-generic

Parameters

...	A comma-separated list of the names of members/variables which provide the capabilities to be released. If omitted, assumed to be `this` .

◆ ARENE_TSA_RELEASE_SHARED

#define ARENE_TSA_RELEASE_SHARED ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(release_shared_capability(__VA_ARGS__))

Annotates a function or method as releasing access to the named capabilities before exit. The calling thread must hold shared access to the named capabilities before entering.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#acquire-acquire-shared-release-release-shared-release-generic

Parameters

...	A comma-separated list of the names of members/variables which provide the capabilities to be released. If omitted, assumed to be `this` .

◆ ARENE_TSA_REQUIRES

#define ARENE_TSA_REQUIRES ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(requires_capability(__VA_ARGS__))

Annotates a function or method as needing the calling thread to hold exclusive access to the named capabilities before entering and after exit.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#requires-requires-shared

Parameters

...	A comma-separated list of the names of members/variables which provide the needed capabilities.

◆ ARENE_TSA_REQUIRES_SHARED

#define ARENE_TSA_REQUIRES_SHARED ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(requires_shared_capability(__VA_ARGS__))

Annotates a function or method as needing the calling thread to hold shared access to the named capabilities before entering and after exit.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#requires-requires-shared

Parameters

...	A comma-separated list of the names of members/variables which provide the needed capabilities.

◆ ARENE_TSA_RETURN_CAPABILITY

#define ARENE_TSA_RETURN_CAPABILITY ( x )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(lock_returned(x))

Annotates a function or method as returning a reference to the named capability.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#return-capability-c

Parameters

x	The name of the member or variable that provides the needed capability

◆ ARENE_TSA_SCOPED_CAPABILITY

#define ARENE_TSA_SCOPED_CAPABILITY ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(scoped_lockable)

Annotates a type as a "scoped capability," which is a type that provides RAII synchronization protection.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#scoped-capability

◆ ARENE_TSA_TRY_ACQUIRE

#define ARENE_TSA_TRY_ACQUIRE ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(try_acquire_capability(__VA_ARGS__))

Annotates a function or method as attempting to acquire exclusive access to the named capabilities before exit, without releasing them on exit, and returning a bool of success/failure.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#try-acquire-bool-try-acquire-shared-bool

Parameters

... A boolean value, followed by a comma-separated list of the names of members/variables which provide the capabilities to be acquired. The boolean value represents which boolean value represents "success" for the assertion. If the name of the capability(s) are omitted, the capability is assumed to be this .

Warning: Because TSA does not support conditional locking analysis, the capability will assume to have been locked after the first branch based on the return value from the annotated function. Therefore, callers of the annotated function must have the "success" path as the first branch.

◆ ARENE_TSA_TRY_ACQUIRE_SHARED

#define ARENE_TSA_TRY_ACQUIRE_SHARED ( ... )

Value:

ARENE_THREAD_SAFETY_ANNOTATION_ATTRIBUTE_I_(try_acquire_shared_capability(__VA_ARGS__))

Annotates a function or method as attempting to acquire shared access to the named capabilities before exit, without releasing them on exit, and returning a bool of success/failure.

See also: https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#try-acquire-bool-try-acquire-shared-bool

Parameters

... A boolean value, followed by a comma-separated list of the names of members/variables which provide the capabilities to be acquired. The boolean value represents which boolean value represents "success" for the assertion. If the name of the capability(s) are omitted, the capability is assumed to be this .

Warning: Because TSA does not support conditional locking analysis, the capability will assume to have been locked after the first branch based on the return value from the annotated function. Therefore, callers of the annotated function must have the "success" path as the first branch.