libsanitizer/tsan/tsan_interface_java.h

   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
  31 extern "C" {
  32 #endif
  33
  34 typedef unsigned long jptr;
  35
  36 // Must be called before any other callback from Java.
  37 void __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.
  41 int  __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).
  46 void __tsan_java_alloc(jptr ptr, jptr size) INTERFACE_ATTRIBUTE;
  47 // Callback for memory free.
  48 // Can be aggregated for several objects (preferably).
  49 void __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.
  53 void __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.
  58 void __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.
  62 jptr __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.
  67 void __tsan_java_mutex_lock(jptr addr) INTERFACE_ATTRIBUTE;
  68 // Mutex unlock.
  69 void __tsan_java_mutex_unlock(jptr addr) INTERFACE_ATTRIBUTE;
  70 // Mutex read lock.
  71 void __tsan_java_mutex_read_lock(jptr addr) INTERFACE_ATTRIBUTE;
  72 // Mutex read unlock.
  73 void __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().
  77 void __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.
  83 int __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).
  89 void __tsan_java_acquire(jptr addr) INTERFACE_ATTRIBUTE;
  90 void __tsan_java_release(jptr addr) INTERFACE_ATTRIBUTE;
  91 void __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