1//===-- tsan_interface_java.h -----------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// This file is a part of ThreadSanitizer (TSan), a race detector.
10//
11// Interface for verification of Java or mixed Java/C++ programs.
12// The interface is intended to be used from within a JVM and notify TSan
13// about such events like Java locks and GC memory compaction.
14//
15// For plain memory accesses and function entry/exit a JVM is intended to use
16// C++ interfaces: __tsan_readN/writeN and __tsan_func_enter/exit.
17//
18// For volatile memory accesses and atomic operations JVM is intended to use
19// standard atomics API: __tsan_atomicN_load/store/etc.
20//
21// For usage examples see lit_tests/java_*.cpp
22//===----------------------------------------------------------------------===//
23#ifndef TSAN_INTERFACE_JAVA_H
24#define TSAN_INTERFACE_JAVA_H
25
26#ifndef INTERFACE_ATTRIBUTE
27# define INTERFACE_ATTRIBUTE __attribute__((visibility("default")))
28#endif
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34typedef unsigned long jptr;
35
36// Must be called before any other callback from Java.
37void __tsan_java_init(jptr heap_begin, jptr heap_size) INTERFACE_ATTRIBUTE;
38// Must be called when the application exits.
39// Not necessary the last callback (concurrently running threads are OK).
40// Returns exit status or 0 if tsan does not want to override it.
41int __tsan_java_fini() INTERFACE_ATTRIBUTE;
42
43// Callback for memory allocations.
44// May be omitted for allocations that are not subject to data races
45// nor contain synchronization objects (e.g. String).
46void __tsan_java_alloc(jptr ptr, jptr size) INTERFACE_ATTRIBUTE;
47// Callback for memory free.
48// Can be aggregated for several objects (preferably).
49void __tsan_java_free(jptr ptr, jptr size) INTERFACE_ATTRIBUTE;
50// Callback for memory move by GC.
51// Can be aggregated for several objects (preferably).
52// The ranges can overlap.
53void __tsan_java_move(jptr src, jptr dst, jptr size) INTERFACE_ATTRIBUTE;
54// This function must be called on the finalizer thread
55// before executing a batch of finalizers.
56// It ensures necessary synchronization between
57// java object creation and finalization.
58void __tsan_java_finalize() INTERFACE_ATTRIBUTE;
59// Finds the first allocated memory block in the [*from_ptr, to) range, saves
60// its address in *from_ptr and returns its size. Returns 0 if there are no
61// allocated memory blocks in the range.
62jptr __tsan_java_find(jptr *from_ptr, jptr to) INTERFACE_ATTRIBUTE;
63
64// Mutex lock.
65// Addr is any unique address associated with the mutex.
66// Can be called on recursive reentry.
67void __tsan_java_mutex_lock(jptr addr) INTERFACE_ATTRIBUTE;
68// Mutex unlock.
69void __tsan_java_mutex_unlock(jptr addr) INTERFACE_ATTRIBUTE;
70// Mutex read lock.
71void __tsan_java_mutex_read_lock(jptr addr) INTERFACE_ATTRIBUTE;
72// Mutex read unlock.
73void __tsan_java_mutex_read_unlock(jptr addr) INTERFACE_ATTRIBUTE;
74// Recursive mutex lock, intended for handling of Object.wait().
75// The 'rec' value must be obtained from the previous
76// __tsan_java_mutex_unlock_rec().
77void __tsan_java_mutex_lock_rec(jptr addr, int rec) INTERFACE_ATTRIBUTE;
78// Recursive mutex unlock, intended for handling of Object.wait().
79// The return value says how many times this thread called lock()
80// w/o a pairing unlock() (i.e. how many recursive levels it unlocked).
81// It must be passed back to __tsan_java_mutex_lock_rec() to restore
82// the same recursion level.
83int __tsan_java_mutex_unlock_rec(jptr addr) INTERFACE_ATTRIBUTE;
84
85// Raw acquire/release primitives.
86// Can be used to establish happens-before edges on volatile/final fields,
87// in atomic operations, etc. release_store is the same as release, but it
88// breaks release sequence on addr (see C++ standard 1.10/7 for details).
89void __tsan_java_acquire(jptr addr) INTERFACE_ATTRIBUTE;
90void __tsan_java_release(jptr addr) INTERFACE_ATTRIBUTE;
91void __tsan_java_release_store(jptr addr) INTERFACE_ATTRIBUTE;
92
93#ifdef __cplusplus
94} // extern "C"
95#endif
96
97#undef INTERFACE_ATTRIBUTE
98
99#endif // #ifndef TSAN_INTERFACE_JAVA_H
100