0
# C Interoperability
1

2
Comprehensive C interoperability framework providing type-safe integration between Java and C code. Enables direct function calls, struct mapping, pointer operations, and memory management without JNI overhead.
3

4
## Capabilities
5

6
### Function Interoperability
7

8
Direct Java-to-C function calls bypassing JNI protocol for maximum performance.
9

10
```java { .api }
11
/**
12
 * Maps Java methods to C functions for direct calls
13
 */
14
@interface CFunction {
15
    /** C function name (defaults to Java method name) */
16
    String value() default "";
17
    
18
    /** C library name containing the function */
19
    String library() default "";
20
}
21

22
/**
23
 * Marks Java methods as VM entry points accessible from C
24
 */
25
@interface CEntryPoint {
26
    /** C function name for the entry point */
27
    String name() default "";
28
    
29
    /** Documentation string */
30
    String documentation() default "";
31
}
32

33
/**
34
 * Specifies C library dependencies
35
 */
36
@interface CLibrary {
37
    /** Library name or path */
38
    String value();
39
}
40

41
/**
42
 * Pointer to C functions - marker interface for function pointers
43
 */
44
interface CFunctionPointer extends CodePointer, RelocatedPointer {}
45

46
/**
47
 * Relocatable function pointer
48
 */
49
interface CodePointer extends PointerBase {}
50

51
/**
52
 * Relocated code pointer support
53
 */
54
interface RelocatedPointer extends CodePointer {}
55
```
56

57
**Usage Examples:**
58

59
```java
60
// Direct C function calls
61
@CFunction
62
static native int strlen(CCharPointer str);
63

64
@CFunction("custom_malloc")
65
static native VoidPointer allocateMemory(int size);
66

67
@CLibrary("mylib")
68
@CFunction
69
static native void processData(CIntPointer data, int length);
70

71
// Entry points callable from C
72
@CEntryPoint(name = "java_callback")
73
static int callbackFromC(int value) {
74
    return value * 2;
75
}
76

77
// Function pointers
78
interface MathFunction extends CFunctionPointer {
79
    @InvokeCFunctionPointer
80
    double apply(double x);
81
}
82

83
// Using function pointers
84
MathFunction sinFunc = /* get function pointer */;
85
double result = sinFunc.apply(3.14159);
86
```
87

88
### Structure Mapping
89

90
Interface-based mapping of C structures with type-safe field access.
91

92
```java { .api }
93
/**
94
 * Maps Java interfaces to C structures
95
 */
96
@interface CStruct {
97
    /** C struct name (defaults to interface name) */
98
    String value() default "";
99
}
100

101
/**
102
 * Maps interface methods to C struct fields
103
 */
104
@interface CField {
105
    /** C field name (defaults to method name without get/set prefix) */
106
    String value() default "";
107
}
108

109
/**
110
 * Computes address of struct fields
111
 */
112
@interface CFieldAddress {
113
    /** Field name */
114
    String value();
115
}
116

117
/**
118
 * Computes offset of struct fields
119
 */
120
@interface CFieldOffset {
121
    /** Field name */
122
    String value();
123
}
124

125
/**
126
 * Bitfield support within structs
127
 */
128
@interface CBitfield {
129
    /** Bit position */
130
    int position();
131
    
132
    /** Number of bits */
133
    int width();
134
}
135

136
/**
137
 * Low-level struct operations
138
 */
139
interface RawStructure extends PointerBase {
140
    /** Read raw bytes from the structure */
141
    byte readByte(int offset);
142
    
143
    /** Write raw bytes to the structure */
144
    void writeByte(int offset, byte value);
145
}
146
```
147

148
**Usage Examples:**
149

150
```java
151
// Define a C struct mapping
152
@CStruct("point")
153
interface Point extends PointerBase {
154
    @CField("x")
155
    int getX();
156
    
157
    @CField("x") 
158
    void setX(int value);
159
    
160
    @CField("y")
161
    int getY();
162
    
163
    @CField("y")
164
    void setY(int value);
165
}
166

167
// Use the struct
168
Point point = StackValue.get(Point.class);
169
point.setX(10);
170
point.setY(20);
171

172
// Field operations
173
@CFieldAddress("x")
174
static native CIntPointer getXAddress(Point point);
175

176
@CFieldOffset("y")
177
static native int getYOffset();
178

179
// Bitfields
180
@CStruct
181
interface Flags extends PointerBase {
182
    @CBitfield(position = 0, width = 1)
183
    boolean getEnabled();
184
    
185
    @CBitfield(position = 0, width = 1)
186
    void setEnabled(boolean value);
187
    
188
    @CBitfield(position = 1, width = 3)
189
    int getPriority();
190
    
191
    @CBitfield(position = 1, width = 3)
192
    void setPriority(int value);
193
}
194
```
195

196
### Type System and Pointers
197

198
Comprehensive type-safe pointer system for C interoperability.
199

200
```java { .api }
201
/**
202
 * Base interface for word-sized values
203
 */
204
interface WordBase {
205
    /** Convert to raw long value */
206
    long rawValue();
207
}
208

209
/**
210
 * Base interface for all pointer types
211
 */
212
interface PointerBase extends ComparableWord {
213
    /** Check if pointer is null */
214
    boolean isNull();
215
    
216
    /** Check if pointer is non-null */
217
    boolean isNonNull();
218
}
219

220
/**
221
 * Generic word-sized pointer
222
 */
223
interface WordPointer extends PointerBase {
224
    /** Read word value at offset */
225
    WordBase read(int index);
226
    
227
    /** Write word value at offset */
228
    void write(int index, WordBase value);
229
}
230

231
/**
232
 * Pointer to void (opaque data)
233
 */
234
interface VoidPointer extends PointerBase {}
235

236
/**
237
 * Typed pointers for primitive types
238
 */
239
interface CCharPointer extends PointerBase {
240
    byte read();
241
    void write(byte value);
242
    byte read(int index);
243
    void write(int index, byte value);
244
    CCharPointer addressOf(int index);
245
}
246

247
interface CIntPointer extends PointerBase {
248
    int read();
249
    void write(int value);
250
    int read(int index);
251
    void write(int index, int value);
252
    CIntPointer addressOf(int index);
253
}
254

255
interface CLongPointer extends PointerBase {
256
    long read();
257
    void write(long value);
258
    long read(int index);
259
    void write(int index, long value);
260
    CLongPointer addressOf(int index);
261
}
262

263
interface CFloatPointer extends PointerBase {
264
    float read();
265
    void write(float value);
266
    float read(int index);
267
    void write(int index, float value);
268
    CFloatPointer addressOf(int index);
269
}
270

271
interface CDoublePointer extends PointerBase {
272
    double read();
273
    void write(double value);
274
    double read(int index);
275
    void write(int index, double value);
276
    CDoublePointer addressOf(int index);
277
}
278
```
279

280
**Usage Examples:**
281

282
```java
283
// Pointer operations
284
CIntPointer intPtr = StackValue.get(CIntPointer.class);
285
intPtr.write(42);
286
int value = intPtr.read();
287

288
// Array operations
289
CIntPointer array = StackValue.get(10, CIntPointer.class);
290
for (int i = 0; i < 10; i++) {
291
    array.write(i, i * i);
292
}
293

294
// Pointer arithmetic
295
CCharPointer base = /* ... */;
296
CCharPointer offset = base.addressOf(5);
297

298
// Null checks
299
if (ptr.isNonNull()) {
300
    int data = ptr.read();
301
}
302
```
303

304
### Type Conversion and Utilities
305

306
Utilities for converting between Java and C types.
307

308
```java { .api }
309
/**
310
 * Java/C type conversion utilities
311
 */
312
class CTypeConversion {
313
    /** Convert Java string to C string */
314
    static CCharPointer toCString(String javaString);
315
    
316
    /** Convert C string to Java string */
317
    static String toJavaString(CCharPointer cString);
318
    
319
    /** Convert Java byte array to C pointer */
320
    static CCharPointer toCBytes(byte[] javaBytes);
321
    
322
    /** Convert C pointer to Java byte array */
323
    static byte[] toJavaBytes(CCharPointer cBytes, int length);
324
    
325
    /** Create pinned UTF-8 C string from Java string */
326
    static CTypeConversion.CCharPointerHolder toCString(String javaString, Charset charset);
327
}
328

329
/**
330
 * Holder for C strings with automatic cleanup
331
 */
332
interface CTypeConversion.CCharPointerHolder extends AutoCloseable {
333
    /** Get the C string pointer */
334
    CCharPointer get();
335
    
336
    /** Release the C string */
337
    void close();
338
}
339

340
/**
341
 * Size computation for C types
342
 */
343
@interface SizeOf {
344
    /** C type name */
345
    String value();
346
}
347

348
/**
349
 * Type-safe pointer to specific types
350
 */
351
@interface CPointerTo {
352
    /** Target type */
353
    Class<?> value();
354
}
355
```
356

357
**Usage Examples:**
358

359
```java
360
// String conversion
361
String javaStr = "Hello, World!";
362
try (CTypeConversion.CCharPointerHolder holder = CTypeConversion.toCString(javaStr)) {
363
    CCharPointer cStr = holder.get();
364
    int length = strlen(cStr);
365
    System.out.println("C string length: " + length);
366
}
367

368
// Byte array conversion
369
byte[] javaBytes = {1, 2, 3, 4, 5};
370
CCharPointer cBytes = CTypeConversion.toCBytes(javaBytes);
371

372
// Size queries
373
@SizeOf("struct point")
374
static native int pointSize();
375

376
// Type-safe pointers
377
@CPointerTo(Point.class)
378
interface PointPointer extends PointerBase {
379
    Point read();
380
    void write(Point value);
381
}
382
```
383

384
### Constants and Enums
385

386
Mapping of C constants and enums to Java.
387

388
```java { .api }
389
/**
390
 * Maps Java methods to C constants
391
 */
392
@interface CConstant {
393
    /** C constant name */
394
    String value() default "";
395
}
396

397
/**
398
 * Marks interfaces as C enum types
399
 */
400
@interface CEnum {
401
    /** C enum name */
402
    String value() default "";
403
}
404

405
/**
406
 * Maps to individual enum constants
407
 */
408
@interface CEnumConstant {
409
    /** C enum constant name */
410
    String value();
411
}
412

413
/**
414
 * Lookup method for C enum values
415
 */
416
@interface CEnumLookup {}
417

418
/**
419
 * Conversion from Java enum to C enum value
420
 */
421
@interface CEnumValue {}
422
```
423

424
**Usage Examples:**
425

426
```java
427
// C constants
428
@CConstant("EAGAIN")
429
static native int eagain();
430

431
@CConstant("PIPE_BUF")
432
static native int pipeBufferSize();
433

434
// C enums
435
@CEnum("color")
436
enum Color {
437
    @CEnumConstant("COLOR_RED") RED,
438
    @CEnumConstant("COLOR_GREEN") GREEN,
439
    @CEnumConstant("COLOR_BLUE") BLUE;
440
    
441
    @CEnumLookup
442
    static native Color fromValue(int value);
443
    
444
    @CEnumValue
445
    native int getValue();
446
}
447

448
// Using enums
449
Color red = Color.RED;
450
int redValue = red.getValue();
451
Color fromC = Color.fromValue(cEnumValue);
452
```
453

454
### Context and Configuration
455

456
Compilation context and header configuration for C interop.
457

458
```java { .api }
459
/**
460
 * Defines C compilation context and library dependencies
461
 */
462
@interface CContext {
463
    /** Header files to include */
464
    Class<? extends CContext.Directives>[] value();
465
}
466

467
/**
468
 * Specifies C header files to be parsed
469
 */
470
@interface CHeader {
471
    /** Header file names or paths */
472
    String[] value();
473
}
474

475
/**
476
 * Type modifiers for C types
477
 */
478
@interface CConst {}
479
@interface CUnsigned {}
480
```
481

482
**Usage Examples:**
483

484
```java
485
// Context definition
486
@CContext(MyDirectives.class)
487
public class MyCInterop {
488
    
489
    static class MyDirectives implements CContext.Directives {
490
        @Override
491
        public List<String> getHeaderFiles() {
492
            return Arrays.asList("<stdio.h>", "<stdlib.h>", "myheader.h");
493
        }
494
        
495
        @Override
496
        public List<String> getLibraries() {
497
            return Arrays.asList("mylib");
498
        }
499
    }
500
}
501

502
// Header inclusion
503
@CHeader({"<unistd.h>", "<sys/types.h>"})
504
public class UnixInterop {
505
    @CFunction
506
    static native int getpid();
507
    
508
    @CFunction
509
    static native CCharPointer getenv(CCharPointer name);
510
}
511

512
// Type modifiers
513
@CStruct
514
interface FileInfo extends PointerBase {
515
    @CField
516
    @CConst
517
    CCharPointer getName();
518
    
519
    @CField
520
    @CUnsigned
521
    int getSize();
522
}
523
```
524

525
This C interoperability framework enables seamless integration between Java and C code while maintaining type safety and performance. It eliminates JNI overhead through direct function calls and provides comprehensive support for C data structures, memory management, and type conversions.