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