0
# Platform Operations
1

2
Direct memory access and platform-specific operations using sun.misc.Unsafe for maximum performance in big data processing scenarios. This module provides the foundational low-level operations that enable Spark's high-performance data processing capabilities.
3

4
## Capabilities
5

6
### Direct Memory Access
7

8
Methods for reading and writing primitive values directly to/from memory addresses, bypassing Java's normal memory access restrictions for maximum performance.
9

10
```java { .api }
11
public static int getInt(Object object, long offset);
12
public static void putInt(Object object, long offset, int value);
13
public static boolean getBoolean(Object object, long offset);
14
public static void putBoolean(Object object, long offset, boolean value);
15
public static byte getByte(Object object, long offset);
16
public static void putByte(Object object, long offset, byte value);
17
public static short getShort(Object object, long offset);
18
public static void putShort(Object object, long offset, short value);
19
public static long getLong(Object object, long offset);
20
public static void putLong(Object object, long offset, long value);
21
public static float getFloat(Object object, long offset);
22
public static void putFloat(Object object, long offset, float value);
23
public static double getDouble(Object object, long offset);
24
public static void putDouble(Object object, long offset, double value);
25
```
26

27
### Volatile Memory Operations  
28

29
Memory operations with volatile semantics for thread-safe object reference access.
30

31
```java { .api }
32
public static Object getObjectVolatile(Object object, long offset);
33
public static void putObjectVolatile(Object object, long offset, Object value);
34
```
35

36
### Off-Heap Memory Management
37

38
Low-level memory allocation and deallocation operations for managing off-heap memory directly.
39

40
```java { .api }
41
public static long allocateMemory(long size);
42
public static void freeMemory(long address);
43
public static long reallocateMemory(long address, long oldSize, long newSize);
44
public static ByteBuffer allocateDirectBuffer(int size);
45
```
46

47
### Memory Manipulation
48

49
Bulk memory operations for efficient data movement and initialization.
50

51
```java { .api }
52
public static void setMemory(Object object, long offset, long size, byte value);
53
public static void setMemory(long address, byte value, long size);
54
public static void copyMemory(Object src, long srcOffset, Object dst, long dstOffset, long length);
55
```
56

57
### Platform Information
58

59
Methods to query platform capabilities and characteristics.
60

61
```java { .api }
62
public static boolean cleanerCreateMethodIsDefined();
63
public static boolean unaligned();
64
```
65

66
### Exception Handling
67

68
Utility for throwing exceptions that bypass compiler checks.
69

70
```java { .api }
71
public static void throwException(Throwable t);
72
```
73

74
### Array Base Offsets
75

76
Constants providing the base memory offsets for different array types, used for direct array access.
77

78
```java { .api }
79
public static final int BOOLEAN_ARRAY_OFFSET;
80
public static final int BYTE_ARRAY_OFFSET;
81
public static final int SHORT_ARRAY_OFFSET;
82
public static final int INT_ARRAY_OFFSET;
83
public static final int LONG_ARRAY_OFFSET;
84
public static final int FLOAT_ARRAY_OFFSET;
85
public static final int DOUBLE_ARRAY_OFFSET;
86
```
87

88
## Unsafe Aligned Offset Operations
89

90
Utility operations for managing record length offsets across different platforms with proper alignment handling provided by the UnsafeAlignedOffset class.
91

92
### UAO Size Management
93

94
Methods for managing the Unsafe Aligned Offset size, which varies between 4 and 8 bytes depending on the platform.
95

96
```java { .api }
97
public class UnsafeAlignedOffset {
98
    public static void setUaoSize(int size);
99
    public static int getUaoSize();
100
    public static int getSize(Object object, long offset);
101
    public static void putSize(Object object, long offset, int value);
102
}
103
```
104

105
## Usage Examples
106

107
### Basic Memory Operations
108

109
```java
110
import org.apache.spark.unsafe.Platform;
111

112
// Allocate 1KB of off-heap memory
113
long address = Platform.allocateMemory(1024);
114

115
// Write and read values
116
Platform.putLong(null, address, 123456789L);
117
long value = Platform.getLong(null, address);
118

119
// Fill memory with specific byte value
120
Platform.setMemory(null, address, 1024, (byte) 0xFF);
121

122
// Free the memory
123
Platform.freeMemory(address);
124
```
125

126
### Array Access
127

128
```java
129
import org.apache.spark.unsafe.Platform;
130

131
byte[] array = new byte[100];
132
long offset = Platform.BYTE_ARRAY_OFFSET;
133

134
// Direct array access
135
Platform.putByte(array, offset + 10, (byte) 42);
136
byte value = Platform.getByte(array, offset + 10);
137
```
138

139
### Memory Copying
140

141
```java
142
import org.apache.spark.unsafe.Platform;
143

144
byte[] source = "Hello World".getBytes();
145
byte[] dest = new byte[source.length];
146

147
// High-performance memory copy
148
Platform.copyMemory(
149
    source, Platform.BYTE_ARRAY_OFFSET,
150
    dest, Platform.BYTE_ARRAY_OFFSET,
151
    source.length
152
);
153
```