| // Copyright 2017 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| #pragma once |
| |
| // This header defines thread annotation macros to be used everywhere in Zircon |
| // outside of publicly exposed headers. See system/public/zircon/compiler.h for |
| // the publicly exported macros. |
| |
| // The thread safety analysis system is documented at |
| // http://clang.llvm.org/docs/ThreadSafetyAnalysis.html and its use in Zircon is documented at |
| // docs/thread_annotations.md. The macros we use are: |
| // |
| // TA_CAP(x) |x| is the capability this type represents, e.g. "mutex". |
| // TA_GUARDED(x) the annotated variable is guarded by the capability (e.g. lock) |x| |
| // TA_ACQ(x) function acquires the mutex |x| |
| // TA_ACQ_SHARED(x) function acquires the mutex |x| for shared reading |
| // TA_ACQ_BEFORE(x) Indicates that if both this mutex and muxex |x| are to be acquired, |
| // that this mutex must be acquired before mutex |x|. |
| // TA_ACQ_AFTER(x) Indicates that if both this mutex and muxex |x| are to be acquired, |
| // that this mutex must be acquired after mutex |x|. |
| // TA_TRY_ACQ(bool, x) function acquires the mutex |x| if the function returns |bool| |
| // TA_TRY_ACQ_SHARED(bool, x) function acquires the mutex |x| for shared reading if the function |
| // returns |bool| |
| // TA_REL(x) function releases the mutex |x| |
| // TA_REL_SHARED(x) function releases the shared for reading mutex |x| |
| // TA_ASSERT(x) function asserts that |x| is held |
| // TA_ASSERT_SHARED(x) function asserts that |x| is held for shared reading |
| // TA_REQ(x) function requires that the caller hold the mutex |x| |
| // TA_REQ_SHARED(x) function requires that the caller hold the mutex |x| for shared |
| // reading TA_EXCL(x) function requires that the caller not be holding the mutex |
| // |x| TA_RET_CAP(x) function returns a reference to the mutex |x| TA_SCOPED_CAP type |
| // represents a scoped or RAII-style wrapper around a capability TA_NO_THREAD_SAFETY_ANALYSIS |
| // function is excluded entirely from thread safety analysis |
| |
| #ifdef __clang__ |
| #define THREAD_ANNOTATION(x) __attribute__((x)) |
| #else |
| #define THREAD_ANNOTATION(x) |
| #endif |
| |
| #define TA_CAP(x) THREAD_ANNOTATION(capability(x)) |
| #define TA_GUARDED(x) THREAD_ANNOTATION(guarded_by(x)) |
| #define TA_ACQ(...) THREAD_ANNOTATION(acquire_capability(__VA_ARGS__)) |
| #define TA_ACQ_SHARED(...) THREAD_ANNOTATION(acquire_shared_capability(__VA_ARGS__)) |
| #define TA_ACQ_BEFORE(...) THREAD_ANNOTATION(acquired_before(__VA_ARGS__)) |
| #define TA_ACQ_AFTER(...) THREAD_ANNOTATION(acquired_after(__VA_ARGS__)) |
| #define TA_TRY_ACQ(...) THREAD_ANNOTATION(try_acquire_capability(__VA_ARGS__)) |
| #define TA_TRY_ACQ_SHARED(...) THREAD_ANNOTATION(try_acquire_shared_capability(__VA_ARGS__)) |
| #define TA_REL(...) THREAD_ANNOTATION(release_capability(__VA_ARGS__)) |
| #define TA_REL_SHARED(...) THREAD_ANNOTATION(release_shared_capability(__VA_ARGS__)) |
| #define TA_ASSERT(...) THREAD_ANNOTATION(assert_capability(__VA_ARGS__)) |
| #define TA_ASSERT_SHARED(...) THREAD_ANNOTATION(assert_shared_capability(__VA_ARGS__)) |
| #define TA_REQ(...) THREAD_ANNOTATION(requires_capability(__VA_ARGS__)) |
| #define TA_REQ_SHARED(...) THREAD_ANNOTATION(requires_shared_capability(__VA_ARGS__)) |
| #define TA_EXCL(...) THREAD_ANNOTATION(locks_excluded(__VA_ARGS__)) |
| #define TA_RET_CAP(x) THREAD_ANNOTATION(lock_returned(x)) |
| #define TA_SCOPED_CAP THREAD_ANNOTATION(scoped_lockable) |
| #define TA_NO_THREAD_SAFETY_ANALYSIS THREAD_ANNOTATION(no_thread_safety_analysis) |
