0
# Low-Level Memory Access
1

2
Type-safe APIs for machine-word-sized values and direct memory access, designed to compile to efficient native code without overhead from Java object model.
3

4
## Capabilities
5

6
### Word Types
7

8
Base interfaces for machine-word-sized values with arithmetic operations that compile directly to native instructions.
9

10
```java { .api }
11
/**
12
 * Base interface for all word-sized value types
13
 */
14
public interface WordBase {
15
    /** Convert word to raw long value */
16
    long rawValue();
17
}
18

19
/**
20
 * Word values that support comparison operations
21
 */
22
public interface ComparableWord extends WordBase {
23
    /** Test equality with another word */
24
    boolean equal(ComparableWord val);
25
    
26
    /** Test inequality with another word */
27
    boolean notEqual(ComparableWord val);
28
    
29
    /** Test if this word is less than another */
30
    boolean lessThan(ComparableWord val);
31
    
32
    /** Test if this word is less than or equal to another */
33
    boolean lessOrEqual(ComparableWord val);
34
    
35
    /** Test if this word is greater than another */
36
    boolean greaterThan(ComparableWord val);
37
    
38
    /** Test if this word is greater than or equal to another */
39
    boolean greaterOrEqual(ComparableWord val);
40
    
41
    /** Get word representing value above this word */
42
    ComparableWord aboveThan(ComparableWord val);
43
    
44
    /** Get word representing value below this word */
45
    ComparableWord belowThan(ComparableWord val);
46
    
47
    /** Get word representing value above or equal to this word */
48
    ComparableWord aboveOrEqual(ComparableWord val);
49
    
50
    /** Get word representing value below or equal to this word */
51
    ComparableWord belowOrEqual(ComparableWord val);
52
}
53
```
54

55
**Usage Examples:**
56

57
```java
58
import org.graalvm.word.*;
59

60
public class WordComparison {
61
    public void compareWords() {
62
        UnsignedWord a = WordFactory.unsigned(100);
63
        UnsignedWord b = WordFactory.unsigned(200);
64
        
65
        if (a.lessThan(b)) {
66
            System.out.println("a is less than b");
67
        }
68
        
69
        if (a.notEqual(b)) {
70
            System.out.println("a and b are different");
71
        }
72
        
73
        // Raw value access
74
        long rawA = a.rawValue(); // 100
75
    }
76
}
77
```
78

79
### Unsigned Arithmetic
80

81
Unsigned word operations providing overflow-safe arithmetic that compiles to efficient native code.
82

83
```java { .api }
84
/**
85
 * Unsigned word with arithmetic operations
86
 */
87
public interface UnsignedWord extends ComparableWord {
88
    /** Add unsigned value */
89
    UnsignedWord add(UnsignedWord val);
90
    
91
    /** Add signed integer value */
92
    UnsignedWord add(int val);
93
    
94
    /** Subtract unsigned value */
95
    UnsignedWord subtract(UnsignedWord val);
96
    
97
    /** Subtract signed integer value */
98
    UnsignedWord subtract(int val);
99
    
100
    /** Multiply by unsigned value */
101
    UnsignedWord multiply(UnsignedWord val);
102
    
103
    /** Multiply by signed integer value */
104
    UnsignedWord multiply(int val);
105
    
106
    /** Unsigned division */
107
    UnsignedWord unsignedDivide(UnsignedWord val);
108
    
109
    /** Unsigned remainder */
110
    UnsignedWord unsignedRemainder(UnsignedWord val);
111
    
112
    /** Shift left by number of bits */
113
    UnsignedWord shiftLeft(UnsignedWord n);
114
    
115
    /** Unsigned shift right by number of bits */
116
    UnsignedWord unsignedShiftRight(UnsignedWord n);
117
    
118
    /** Bitwise AND operation */
119
    UnsignedWord and(UnsignedWord val);
120
    
121
    /** Bitwise OR operation */
122
    UnsignedWord or(UnsignedWord val);
123
    
124
    /** Bitwise XOR operation */
125
    UnsignedWord xor(UnsignedWord val);
126
    
127
    /** Bitwise NOT operation */
128
    UnsignedWord not();
129
}
130
```
131

132
**Usage Examples:**
133

134
```java
135
public class UnsignedArithmetic {
136
    public void performCalculations() {
137
        UnsignedWord size = WordFactory.unsigned(1024);
138
        UnsignedWord blockSize = WordFactory.unsigned(64);
139
        
140
        // Calculate number of blocks
141
        UnsignedWord numBlocks = size.unsignedDivide(blockSize);
142
        System.out.println("Number of blocks: " + numBlocks.rawValue()); // 16
143
        
144
        // Align size to block boundary
145
        UnsignedWord mask = blockSize.subtract(1);
146
        UnsignedWord aligned = size.add(mask).and(mask.not());
147
        
148
        // Safe overflow handling
149
        UnsignedWord maxValue = WordFactory.unsigned(Long.MAX_VALUE);
150
        UnsignedWord result = maxValue.add(1); // Wraps around safely
151
        
152
        // Bit manipulation
153
        UnsignedWord flags = WordFactory.unsigned(0);
154
        flags = flags.or(WordFactory.unsigned(0x01)); // Set bit 0
155
        flags = flags.and(WordFactory.unsigned(0xFE).not()); // Clear bit 0
156
    }
157
}
158
```
159

160
### Signed Arithmetic
161

162
Signed word operations with overflow detection and two's complement arithmetic.
163

164
```java { .api }
165
/**
166
 * Signed word with arithmetic operations
167
 */
168
public interface SignedWord extends ComparableWord {
169
    /** Add signed value */
170
    SignedWord add(SignedWord val);
171
    
172
    /** Add integer value */
173
    SignedWord add(int val);
174
    
175
    /** Subtract signed value */
176
    SignedWord subtract(SignedWord val);
177
    
178
    /** Subtract integer value */
179
    SignedWord subtract(int val);
180
    
181
    /** Multiply by signed value */
182
    SignedWord multiply(SignedWord val);
183
    
184
    /** Multiply by integer value */
185
    SignedWord multiply(int val);
186
    
187
    /** Signed division */
188
    SignedWord signedDivide(SignedWord val);
189
    
190
    /** Signed remainder */
191
    SignedWord signedRemainder(SignedWord val);
192
    
193
    /** Shift left by number of bits */
194
    SignedWord shiftLeft(UnsignedWord n);
195
    
196
    /** Signed shift right by number of bits */
197
    SignedWord signedShiftRight(UnsignedWord n);
198
    
199
    /** Bitwise AND operation */
200
    SignedWord and(SignedWord val);
201
    
202
    /** Bitwise OR operation */
203
    SignedWord or(SignedWord val);
204
    
205
    /** Bitwise XOR operation */
206
    SignedWord xor(SignedWord val);
207
    
208
    /** Bitwise NOT operation */
209
    SignedWord not();
210
}
211
```
212

213
### Pointer Operations
214

215
Type-safe pointer arithmetic and memory access operations.
216

217
```java { .api }
218
/**
219
 * Base interface for pointer types
220
 */
221
public interface PointerBase extends ComparableWord {
222
    /** Check if pointer is null */
223
    boolean isNull();
224
    
225
    /** Check if pointer is not null */
226
    boolean isNonNull();
227
}
228

229
/**
230
 * Pointer with arithmetic and memory access operations
231
 */
232
public interface Pointer extends UnsignedWord, PointerBase {
233
    /** Read byte at offset */
234
    byte readByte(UnsignedWord offset);
235
    
236
    /** Read byte at word-sized offset */
237
    byte readByte(int wordOffset);
238
    
239
    /** Write byte at offset */
240
    void writeByte(UnsignedWord offset, byte val);
241
    
242
    /** Write byte at word-sized offset */
243
    void writeByte(int wordOffset, byte val);
244
    
245
    /** Read char at offset */
246
    char readChar(UnsignedWord offset);
247
    
248
    /** Write char at offset */
249
    void writeChar(UnsignedWord offset, char val);
250
    
251
    /** Read short at offset */
252
    short readShort(UnsignedWord offset);
253
    
254
    /** Write short at offset */
255
    void writeShort(UnsignedWord offset, short val);
256
    
257
    /** Read int at offset */
258
    int readInt(UnsignedWord offset);
259
    
260
    /** Write int at offset */
261
    void writeInt(UnsignedWord offset, int val);
262
    
263
    /** Read long at offset */
264
    long readLong(UnsignedWord offset);
265
    
266
    /** Write long at offset */
267
    void writeLong(UnsignedWord offset, long val);
268
    
269
    /** Read float at offset */
270
    float readFloat(UnsignedWord offset);
271
    
272
    /** Write float at offset */
273
    void writeFloat(UnsignedWord offset, float val);
274
    
275
    /** Read double at offset */
276
    double readDouble(UnsignedWord offset);
277
    
278
    /** Write double at offset */
279
    void writeDouble(UnsignedWord offset, double val);
280
    
281
    /** Read word at offset */
282
    <T extends WordBase> T readWord(UnsignedWord offset);
283
    
284
    /** Write word at offset */
285
    void writeWord(UnsignedWord offset, WordBase val);
286
    
287
    /** Read object reference at offset */
288
    Object readObject(UnsignedWord offset);
289
    
290
    /** Write object reference at offset */
291
    void writeObject(UnsignedWord offset, Object val);
292
    
293
    /** Compare memory regions */
294
    int compareAndSwapInt(UnsignedWord offset, int expectedValue, int newValue);
295
    
296
    /** Compare memory regions for long values */
297
    long compareAndSwapLong(UnsignedWord offset, long expectedValue, long newValue);
298
    
299
    /** Compare memory regions for word values */
300
    <T extends WordBase> T compareAndSwapWord(UnsignedWord offset, T expectedValue, T newValue);
301
    
302
    /** Compare memory regions for object references */
303
    Object compareAndSwapObject(UnsignedWord offset, Object expectedValue, Object newValue);
304
}
305
```
306

307
**Usage Examples:**
308

309
```java
310
public class PointerOperations {
311
    public void accessMemory() {
312
        // Allocate native memory (conceptual - actual allocation varies)
313
        Pointer memory = allocateMemory(1024);
314
        
315
        if (memory.isNonNull()) {
316
            // Write data to memory
317
            memory.writeInt(WordFactory.unsigned(0), 42);
318
            memory.writeInt(WordFactory.unsigned(4), 100);
319
            
320
            // Read data back
321
            int first = memory.readInt(WordFactory.unsigned(0));
322
            int second = memory.readInt(WordFactory.unsigned(4));
323
            
324
            System.out.println("First: " + first + ", Second: " + second);
325
            
326
            // Pointer arithmetic
327
            Pointer secondInt = memory.add(4);
328
            int value = secondInt.readInt(WordFactory.unsigned(0));
329
            
330
            // Atomic operations
331
            int oldValue = memory.compareAndSwapInt(
332
                WordFactory.unsigned(0), 42, 84);
333
            if (oldValue == 42) {
334
                System.out.println("Successfully updated value");
335
            }
336
        }
337
    }
338
    
339
    // Placeholder for memory allocation
340
    private native Pointer allocateMemory(int size);
341
}
342
```
343

344
### Word Factory
345

346
Factory methods for creating word values from primitive types.
347

348
```java { .api }
349
/**
350
 * Factory for creating word values from primitives
351
 */
352
public final class WordFactory {
353
    /** Create zero-valued unsigned word */
354
    public static UnsignedWord zero();
355
    
356
    /** Create null pointer */
357
    public static <T extends PointerBase> T nullPointer();
358
    
359
    /** Create unsigned word from long value */
360
    public static UnsignedWord unsigned(long val);
361
    
362
    /** Create unsigned word from int value */
363
    public static UnsignedWord unsigned(int val);
364
    
365
    /** Create signed word from long value */
366
    public static SignedWord signed(long val);
367
    
368
    /** Create signed word from int value */
369
    public static SignedWord signed(int val);
370
    
371
    /** Create pointer from long address */
372
    public static <T extends PointerBase> T pointer(long val);
373
    
374
    /** Create word from raw value */
375
    public static <T extends WordBase> T fromRawValue(Class<T> type, long rawValue);
376
}
377
```
378

379
**Usage Examples:**
380

381
```java
382
public class WordFactoryUsage {
383
    public void createWords() {
384
        // Create various word types
385
        UnsignedWord pageSize = WordFactory.unsigned(4096);
386
        SignedWord offset = WordFactory.signed(-100);
387
        Pointer nullPtr = WordFactory.nullPointer();
388
        
389
        // Zero and max values
390
        UnsignedWord zero = WordFactory.zero();
391
        UnsignedWord maxUnsigned = WordFactory.unsigned(-1L); // All bits set
392
        
393
        // Convert between types
394
        long rawValue = pageSize.rawValue();
395
        UnsignedWord restored = WordFactory.unsigned(rawValue);
396
        
397
        // Null checks
398
        if (nullPtr.isNull()) {
399
            System.out.println("Pointer is null");
400
        }
401
        
402
        // Create typed pointers
403
        Pointer buffer = WordFactory.pointer(0x1000L);
404
        if (buffer.isNonNull()) {
405
            // Use buffer...
406
        }
407
    }
408
}
409
```
410

411
### Memory Barriers and Synchronization
412

413
Low-level synchronization primitives for concurrent access to memory.
414

415
```java { .api }
416
/**
417
 * Memory synchronization and barriers
418
 */
419
public final class MemoryBarriers {
420
    /** Full memory barrier */
421
    public static void fullBarrier();
422
    
423
    /** Load memory barrier */
424
    public static void loadBarrier();
425
    
426
    /** Store memory barrier */
427
    public static void storeBarrier();
428
    
429
    /** Load-store memory barrier */
430
    public static void loadStoreBarrier();
431
    
432
    /** Store-load memory barrier */
433
    public static void storeLoadBarrier();
434
}
435

436
/**
437
 * Atomic operations on word values
438
 */
439
public final class AtomicOperations {
440
    /** Atomic load with acquire semantics */
441
    public static <T extends WordBase> T loadAcquire(Pointer address);
442
    
443
    /** Atomic store with release semantics */
444
    public static void storeRelease(Pointer address, WordBase value);
445
    
446
    /** Atomic compare-and-swap */
447
    public static <T extends WordBase> T compareAndSwap(
448
        Pointer address, T expectedValue, T newValue);
449
    
450
    /** Atomic fetch-and-add */
451
    public static UnsignedWord fetchAndAdd(Pointer address, UnsignedWord delta);
452
    
453
    /** Atomic fetch-and-subtract */
454
    public static UnsignedWord fetchAndSubtract(Pointer address, UnsignedWord delta);
455
}
456
```
457

458
## Types
459

460
```java { .api }
461
// Platform-specific word sizes
462
public interface WordSize {
463
    /** Get size of machine word in bytes */
464
    static int wordSize();
465
    
466
    /** Get size of pointer in bytes */
467
    static int pointerSize();
468
}
469

470
// Word type constants
471
public final class WordConstants {
472
    /** Maximum unsigned word value */
473
    public static final UnsignedWord MAX_UNSIGNED;
474
    
475
    /** Maximum signed word value */
476
    public static final SignedWord MAX_SIGNED;
477
    
478
    /** Minimum signed word value */
479
    public static final SignedWord MIN_SIGNED;
480
    
481
    /** Word size in bits */
482
    public static final int WORD_SIZE_BITS;
483
    
484
    /** Word size in bytes */
485
    public static final int WORD_SIZE_BYTES;
486
}
487

488
// Exception types
489
public class WordException extends RuntimeException {
490
    public WordException(String message);
491
    public WordException(String message, Throwable cause);
492
}
493
```