1 /* 2 * Copyright (C) 2013 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #pragma once 18 19 #include <sys/cdefs.h> 20 21 #include <stdbool.h> 22 23 __BEGIN_DECLS 24 25 /* 26 * The JNI invocation API exists to allow a choice of library responsible for managing virtual 27 * machines. 28 */ 29 30 /* 31 * Opaque structure used to hold JNI invocation internal state. 32 */ 33 struct JniInvocationImpl; 34 35 /* 36 * Creates an instance of a JniInvocationImpl. 37 */ 38 struct JniInvocationImpl* JniInvocationCreate(); 39 40 /* 41 * Associates a library with a JniInvocationImpl instance. The library should export C symbols for 42 * JNI_GetDefaultJavaVMInitArgs, JNI_CreateJavaVM and JNI_GetDefaultJavaVMInitArgs. 43 * 44 * The specified |library| should be the filename of a shared library. The |library| is opened with 45 * dlopen(3). 46 * 47 * If there is an error opening the specified |library|, then function will fallback to the 48 * default library "libart.so". If the fallback library is successfully used then a warning is 49 * written to the Android log buffer. Use of the fallback library is not considered an error. 50 * 51 * If the fallback library cannot be opened or the expected symbols are not found in the library 52 * opened, then an error message is written to the Android log buffer and the function returns 0. 53 * 54 * Returns true on success, false otherwise. 55 */ 56 bool JniInvocationInit(struct JniInvocationImpl* instance, const char* library); 57 58 /* 59 * Release resources associated with JniInvocationImpl instance. 60 */ 61 void JniInvocationDestroy(struct JniInvocationImpl* instance); 62 63 /* 64 * Gets the default library for JNI invocation. The default library is "libart.so". This value may 65 * be overridden for debuggable builds using the persist.sys.dalvik.vm.lib.2 system property. 66 * 67 * The |library| argument is the preferred library to use on debuggable builds (when 68 * ro.debuggable=1). If the |library| argument is nullptr, then the system preferred value will be 69 * queried from persist.sys.dalvik.vm.lib.2 if the caller has provided |buffer| argument. 70 * 71 * The |buffer| argument is used for reading system properties in debuggable builds. It is 72 * optional, but should be provisioned to be PROP_VALUE_MAX bytes if provided to ensure it is 73 * large enough to hold a system property. 74 * 75 * Returns the filename of the invocation library determined from the inputs and system 76 * properties. The returned value may be |library|, |buffer|, or a pointer to a string constant 77 * "libart.so". 78 */ 79 const char* JniInvocationGetLibrary(const char* library, char* buffer); 80 81 __END_DECLS 82 83 #ifdef __cplusplus 84 85 // JniInvocation adds a layer of indirection for applications using 86 // the JNI invocation API to allow the JNI implementation to be 87 // selected dynamically. Apps can specify a specific implementation to 88 // be used by calling InitJniInvocation. If this is not done, the 89 // library will chosen based on the value of Android system property 90 // persist.sys.dalvik.vm.lib on the device, and otherwise fall back to 91 // a hard-coded default implementation. 92 class JniInvocation final { 93 public: JniInvocation()94 JniInvocation() { 95 impl_ = JniInvocationCreate(); 96 } 97 ~JniInvocation()98 ~JniInvocation() { 99 JniInvocationDestroy(impl_); 100 } 101 102 // Initialize JNI invocation API. library should specify a valid 103 // shared library for opening via dlopen providing a JNI invocation 104 // implementation, or null to allow defaulting via 105 // persist.sys.dalvik.vm.lib. Init(const char * library)106 bool Init(const char* library) { 107 return JniInvocationInit(impl_, library) != 0; 108 } 109 110 // Exposes which library is actually loaded from the given name. The 111 // buffer of size PROPERTY_VALUE_MAX will be used to load the system 112 // property for the default library, if necessary. If no buffer is 113 // provided, the fallback value will be used. GetLibrary(const char * library,char * buffer)114 static const char* GetLibrary(const char* library, char* buffer) { 115 return JniInvocationGetLibrary(library, buffer); 116 } 117 118 private: 119 JniInvocation(const JniInvocation&) = delete; 120 JniInvocation& operator=(const JniInvocation&) = delete; 121 122 JniInvocationImpl* impl_; 123 }; 124 125 #endif // __cplusplus 126