1 /*
2  * Copyright (C) 2008 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 #ifndef _ANDROID_NIO_UTILS_H_
18 #define _ANDROID_NIO_UTILS_H_
19 
20 #include <android_runtime/AndroidRuntime.h>
21 
22 namespace android {
23 
24 /**
25  * Class providing scoped access to the memory backing a java.nio.Buffer instance.
26  *
27  * Instances of this class should only be allocated on the stack as heap allocation is not
28  * supported.
29  *
30  * Instances of this class do not create any global references for performance reasons.
31  */
32 class AutoBufferPointer final {
33 public:
34     /** Constructor for an AutoBufferPointer instance.
35      *
36      * @param env          The current JNI env
37      * @param nioBuffer    Instance of a java.nio.Buffer whose memory will be accessed.
38      * @param commit       JNI_TRUE if the underlying memory will be updated and should be
39      *                     copied back to the managed heap. JNI_FALSE if the data will
40      *                     not be modified or the modifications may be discarded.
41      *
42      * The commit parameter is only applicable if the buffer is backed by a managed heap
43      * array and the runtime had to provide a copy of the data rather than the original data.
44      */
45     AutoBufferPointer(JNIEnv* env, jobject nioBuffer, jboolean commit);
46 
47     /** Destructor for an AutoBufferPointer instance.
48      *
49      * Releases critical managed heap array pointer if acquired.
50      */
51     ~AutoBufferPointer();
52 
53     /**
54      * Returns a pointer to the current position of the buffer provided to the constructor.  This
55      * pointer is only valid whilst the AutoBufferPointer instance remains in scope.
56      */
pointer()57     void* pointer() const { return fPointer; }
58 
59 private:
60     JNIEnv* const fEnv;
61     void* fPointer;   // Pointer to current buffer position when constructed.
62     void* fElements;  // Pointer to array element 0 (null if buffer is direct, may be
63                       // within fArray or point to a copy of the array).
64     jarray fArray;    // Pointer to array on managed heap.
65     const jboolean fCommit;  // Flag to commit data to source (when fElements is a copy of fArray).
66 
67     // Unsupported constructors and operators.
68     AutoBufferPointer() = delete;
69     AutoBufferPointer(AutoBufferPointer&) = delete;
70     AutoBufferPointer& operator=(AutoBufferPointer&) = delete;
71     static void* operator new(std::size_t);
72     static void* operator new[](std::size_t);
73     static void* operator new(std::size_t, void*);
74     static void* operator new[](std::size_t, void*);
75     static void operator delete(void*, std::size_t);
76     static void operator delete[](void*, std::size_t);
77 };
78 
79 }   /* namespace android */
80 
81 #endif  // _ANDROID_NIO_UTILS_H_
82