0
# Platform Operations
1

2
Low-level unsafe memory operations and platform-specific functionality providing direct memory access, copying, allocation, and platform feature detection using sun.misc.Unsafe.
3

4
## Capabilities
5

6
### Memory Access Operations
7

8
Direct memory read and write operations for primitive types, bypassing Java's memory safety mechanisms for maximum performance.
9

10
```java { .api }
11
/**
12
 * Core unsafe memory operations and platform-specific functionality
13
 */
14
final class Platform {
15
    // Integer operations
16
    /**
17
     * Read an int value from memory at the specified offset
18
     * @param object Base object (null for off-heap addresses)
19
     * @param offset Offset within object or direct address
20
     * @return int value at the location
21
     */
22
    public static int getInt(Object object, long offset);
23
    
24
    /**
25
     * Write an int value to memory at the specified offset
26
     * @param object Base object (null for off-heap addresses)  
27
     * @param offset Offset within object or direct address
28
     * @param value int value to store
29
     */
30
    public static void putInt(Object object, long offset, int value);
31
    
32
    // Long operations  
33
    /**
34
     * Read a long value from memory at the specified offset
35
     * @param object Base object (null for off-heap addresses)
36
     * @param offset Offset within object or direct address
37
     * @return long value at the location
38
     */
39
    public static long getLong(Object object, long offset);
40
    
41
    /**
42
     * Write a long value to memory at the specified offset
43
     * @param object Base object (null for off-heap addresses)
44
     * @param offset Offset within object or direct address
45
     * @param value long value to store
46
     */
47
    public static void putLong(Object object, long offset, long value);
48
    
49
    // Boolean operations
50
    /**
51
     * Read a boolean value from memory at the specified offset
52
     * @param object Base object (null for off-heap addresses)
53
     * @param offset Offset within object or direct address
54
     * @return boolean value at the location
55
     */
56
    public static boolean getBoolean(Object object, long offset);
57
    
58
    /**
59
     * Write a boolean value to memory at the specified offset
60
     * @param object Base object (null for off-heap addresses)
61
     * @param offset Offset within object or direct address
62
     * @param value boolean value to store
63
     */
64
    public static void putBoolean(Object object, long offset, boolean value);
65
    
66
    // Byte operations
67
    /**
68
     * Read a byte value from memory at the specified offset
69
     * @param object Base object (null for off-heap addresses)
70
     * @param offset Offset within object or direct address
71
     * @return byte value at the location
72
     */
73
    public static byte getByte(Object object, long offset);
74
    
75
    /**
76
     * Write a byte value to memory at the specified offset
77
     * @param object Base object (null for off-heap addresses)
78
     * @param offset Offset within object or direct address
79
     * @param value byte value to store
80
     */
81
    public static void putByte(Object object, long offset, byte value);
82
    
83
    // Short operations
84
    /**
85
     * Read a short value from memory at the specified offset
86
     * @param object Base object (null for off-heap addresses)
87
     * @param offset Offset within object or direct address
88
     * @return short value at the location
89
     */
90
    public static short getShort(Object object, long offset);
91
    
92
    /**
93
     * Write a short value to memory at the specified offset
94
     * @param object Base object (null for off-heap addresses)
95
     * @param offset Offset within object or direct address
96
     * @param value short value to store
97
     */
98
    public static void putShort(Object object, long offset, short value);
99
    
100
    // Float operations
101
    /**
102
     * Read a float value from memory at the specified offset
103
     * @param object Base object (null for off-heap addresses)
104
     * @param offset Offset within object or direct address
105
     * @return float value at the location
106
     */
107
    public static float getFloat(Object object, long offset);
108
    
109
    /**
110
     * Write a float value to memory at the specified offset
111
     * @param object Base object (null for off-heap addresses)
112
     * @param offset Offset within object or direct address
113
     * @param value float value to store
114
     */
115
    public static void putFloat(Object object, long offset, float value);
116
    
117
    // Double operations
118
    /**
119
     * Read a double value from memory at the specified offset
120
     * @param object Base object (null for off-heap addresses)
121
     * @param offset Offset within object or direct address
122
     * @return double value at the location
123
     */
124
    public static double getDouble(Object object, long offset);
125
    
126
    /**
127
     * Write a double value to memory at the specified offset
128
     * @param object Base object (null for off-heap addresses)
129
     * @param offset Offset within object or direct address
130
     * @param value double value to store
131
     */
132
    public static void putDouble(Object object, long offset, double value);
133
}
134
```
135

136
**Usage Examples:**
137

138
```java
139
import org.apache.spark.unsafe.Platform;
140

141
// Reading and writing to a byte array
142
byte[] data = new byte[16];
143
Platform.putLong(data, Platform.BYTE_ARRAY_OFFSET, 42L);
144
long value = Platform.getLong(data, Platform.BYTE_ARRAY_OFFSET);
145

146
// Working with off-heap memory
147
long address = Platform.allocateMemory(1024);
148
try {
149
    Platform.putInt(null, address, 123);
150
    int storedValue = Platform.getInt(null, address);
151
} finally {
152
    Platform.freeMemory(address);
153
}
154
```
155

156
### Volatile Memory Operations
157

158
Memory operations with volatile semantics for concurrent programming scenarios.
159

160
```java { .api }
161
/**
162
 * Read an object reference with volatile semantics
163
 * @param object Base object
164
 * @param offset Offset within object
165
 * @return Object reference at the location
166
 */
167
public static Object getObjectVolatile(Object object, long offset);
168

169
/**
170
 * Write an object reference with volatile semantics
171
 * @param object Base object
172
 * @param offset Offset within object  
173
 * @param value Object reference to store
174
 */
175
public static void putObjectVolatile(Object object, long offset, Object value);
176
```
177

178
### Memory Allocation and Management
179

180
Direct memory allocation and deallocation operations for off-heap memory management.
181

182
```java { .api }
183
/**
184
 * Allocate off-heap memory
185
 * @param size Size in bytes to allocate
186
 * @return Address of allocated memory
187
 * @throws OutOfMemoryError if allocation fails
188
 */
189
public static long allocateMemory(long size);
190

191
/**
192
 * Free previously allocated off-heap memory
193
 * @param address Address of memory to free
194
 */
195
public static void freeMemory(long address);
196

197
/**
198
 * Reallocate off-heap memory to a new size
199
 * @param address Address of existing memory
200
 * @param oldSize Previous size in bytes
201
 * @param newSize New size in bytes
202
 * @return Address of reallocated memory (may be different)
203
 */
204
public static long reallocateMemory(long address, long oldSize, long newSize);
205

206
/**
207
 * Allocate a direct ByteBuffer
208
 * @param size Size in bytes
209
 * @return Direct ByteBuffer of specified size
210
 */
211
public static ByteBuffer allocateDirectBuffer(int size);
212
```
213

214
### Memory Copy and Fill Operations
215

216
Efficient memory copying and filling operations optimized for bulk data movement.
217

218
```java { .api }
219
/**
220
 * Copy memory from source to destination
221
 * @param src Source object (null for off-heap)
222
 * @param srcOffset Source offset or address
223
 * @param dst Destination object (null for off-heap)
224
 * @param dstOffset Destination offset or address
225
 * @param length Number of bytes to copy
226
 */
227
public static void copyMemory(Object src, long srcOffset, Object dst, long dstOffset, long length);
228

229
/**
230
 * Fill memory region with a specific byte value
231
 * @param object Base object (null for off-heap)
232
 * @param offset Offset within object or direct address
233
 * @param size Number of bytes to fill
234
 * @param value Byte value to fill with
235
 */
236
public static void setMemory(Object object, long offset, long size, byte value);
237

238
/**
239
 * Fill off-heap memory region with a specific byte value
240
 * @param address Direct memory address
241
 * @param value Byte value to fill with
242
 * @param size Number of bytes to fill
243
 */
244
public static void setMemory(long address, byte value, long size);
245
```
246

247
**Usage Examples:**
248

249
```java
250
import org.apache.spark.unsafe.Platform;
251

252
// Memory copying between arrays
253
byte[] source = "Hello".getBytes();
254
byte[] dest = new byte[source.length];
255

256
Platform.copyMemory(
257
    source, Platform.BYTE_ARRAY_OFFSET,
258
    dest, Platform.BYTE_ARRAY_OFFSET,
259
    source.length
260
);
261

262
// Fill array with zeros
263
byte[] buffer = new byte[1024];
264
Platform.setMemory(buffer, Platform.BYTE_ARRAY_OFFSET, buffer.length, (byte) 0);
265

266
// Working with off-heap memory
267
long srcAddr = Platform.allocateMemory(100);
268
long dstAddr = Platform.allocateMemory(100);
269
try {
270
    Platform.setMemory(srcAddr, (byte) 0xFF, 100);
271
    Platform.copyMemory(null, srcAddr, null, dstAddr, 100);
272
} finally {
273
    Platform.freeMemory(srcAddr);
274
    Platform.freeMemory(dstAddr);
275
}
276
```
277

278
### Platform Detection
279

280
Methods to detect platform capabilities and features for optimization purposes.
281

282
```java { .api }
283
/**
284
 * Check if platform supports unaligned memory access
285
 * @return true if unaligned access is supported
286
 */
287
public static boolean unaligned();
288

289
/**
290
 * Check if cleaner creation method is available
291
 * @return true if cleaner method is defined
292
 */
293
public static boolean cleanerCreateMethodIsDefined();
294
```
295

296
### Exception Handling
297

298
Utility for bypassing Java's exception checking mechanisms.
299

300
```java { .api }
301
/**
302
 * Throw an exception bypassing compiler checks
303
 * @param t Throwable to throw
304
 */
305
public static void throwException(Throwable t);
306
```
307

308
### Array Offset Constants
309

310
Pre-calculated offsets for different array types to optimize array access operations.
311

312
```java { .api }
313
// Array base offsets for different primitive types
314
public static final int BOOLEAN_ARRAY_OFFSET;  // Offset for boolean arrays
315
public static final int BYTE_ARRAY_OFFSET;     // Offset for byte arrays  
316
public static final int SHORT_ARRAY_OFFSET;    // Offset for short arrays
317
public static final int INT_ARRAY_OFFSET;      // Offset for int arrays
318
public static final int LONG_ARRAY_OFFSET;     // Offset for long arrays
319
public static final int FLOAT_ARRAY_OFFSET;    // Offset for float arrays
320
public static final int DOUBLE_ARRAY_OFFSET;   // Offset for double arrays
321
```
322

323
**Usage Examples:**
324

325
```java
326
import org.apache.spark.unsafe.Platform;
327

328
// Efficient array access using pre-calculated offsets
329
int[] array = {1, 2, 3, 4, 5};
330

331
// Read first element
332
int first = Platform.getInt(array, Platform.INT_ARRAY_OFFSET);
333

334
// Write to second element  
335
Platform.putInt(array, Platform.INT_ARRAY_OFFSET + 4, 999);
336

337
// Check platform capabilities
338
if (Platform.unaligned()) {
339
    // Can use unaligned memory access optimizations
340
    System.out.println("Platform supports unaligned access");
341
}
342
```
343

344
## Performance Considerations
345

346
- **Zero Bounds Checking**: All Platform methods bypass Java bounds checking for maximum performance
347
- **Native Optimization**: Operations compile to native CPU instructions when possible
348
- **Memory Alignment**: Use unaligned() check to optimize for platform-specific alignment requirements
349
- **Batch Operations**: Use copyMemory() and setMemory() for bulk operations rather than individual element access
350
- **Direct Buffer Allocation**: Use allocateDirectBuffer() for I/O operations requiring direct memory
351

352
## Safety Warnings
353

354
⚠️ **Important**: Platform operations bypass Java's memory safety mechanisms:
355
- No bounds checking is performed
356
- Invalid memory access can crash the JVM
357
- Memory leaks are possible with off-heap allocation
358
- Always validate parameters before calling Platform methods
359
- Use try-finally blocks to ensure memory cleanup