forked from WheretIB/nullc
-
Notifications
You must be signed in to change notification settings - Fork 0
/
LibraryEN.html
509 lines (502 loc) · 23.1 KB
/
LibraryEN.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
<!DOCTYPE html>
<html>
<head>
<title>NULLC library reference</title>
<style type="text/css">
p.code
{
background: #eee;
font-family: Consolas, Courier New, monospace;
font-size: 10pt;
}
span.code
{
background: #eee;
font-family: Consolas, Courier New, monospace;
font-size: 10pt;
}
span.rword
{
color: #00f;
}
span.func
{
color: #880000;
font-style: italic;
}
span.var
{
color: #555;
}
span.real
{
color: #008800;
}
span.comment
{
color: #f0f;
}
span.string
{
color: #880000;
}
div.topic
{
margin-left: 20px;
}
div.subtopic
{
margin-left: 20px;
}
p.example_head
{
font-weight: bold;
cursor: pointer;
background-color: #dfd;
}
p.example_body
{
display: none;
margin-left: 10px;
}
div.example
{
}
div.function
{
border: 1px dashed #000;
margin-bottom: 0.5em;
padding-left: 10px;
}
div.function > p
{
margin-top: 0px;
margin-left: 40px;
}
</style>
<script language="javascript" type="text/javascript">
var hashMap = new Array();
function toggleView(a, b, c)
{
if(hashMap[a] == undefined)
hashMap[a] = 1;
else
hashMap[a] = 1 - hashMap[a];
document.getElementById(b).style.display = hashMap[a] ? "block" : "none";
document.getElementById(a).innerHTML = (hashMap[a] ? "Hide " : "Show ") + c;
}
</script>
</head>
<body>
<h2 align="center">NULLC library reference</h2>
<ol>
<li>Interface</li>
<ol>
<li><a href="#lib_compile">Library compilation options</a></li>
<li><a href="#init_term">Initialization and termination</a></li>
<li><a href="#exec_env">Execution settings and environment</a></li>
<li><a href="#basic">Basic functions</a></li>
<li><a href="#interact_func">Interaction functions</a></li>
<li><a href="#special">Special modules</a></li>
<li><a href="#extended">Extended functions</a></li>
<li><a href="#debug">Debug functions</a></li>
</ol>
<li>Interoperability with C code</li>
<ol>
<li><a href="#interop_bind">Binding functions to NULLC</a></li>
</ol>
</ol>
<hr />
<h2 align="center">1. Interface</h2>
<div class="topic">
<h3><a name="lib_compile">1.1 Library compilation options</a></h3>
Various library configuration options are available in "nullcdef.h" file.<br />
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_MAX_VARIABLE_NAME_LENGTH</span> <span class="real">2048</span><br />
</p>
This define control the maximum variable, function or class name that NULLC will attempt to handle.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_DEFAULT_GLOBAL_MEMORY_LIMIT</span> <span class="real">1024 * 1024 * 1024</span><br />
</p>
This define control the default maximum global memory limit (1Gb by default).<br />
You can change this constant or use the <a href="#nullcSetGlobalMemoryLimit">nullcSetGlobalMemoryLimit</a> function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_STACK_TRACE_WITH_LOCALS</span><br />
</p>
This define control whether NULLC will write information about locals in call stack on execution error.<br />
This define is enabled by default.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_ENABLE_C_TRANSLATION</span><br />
</p>
This define enables an ability to translate NULLC code into C++ code.<br />
Keep in mind that enabling this define will degrade performance of NULLC VM and JiT executors (additionally, NULLC_OPTIMIZE_X86 will be disabled).<br />
This define is disabled by default.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_PURE_FUNCTIONS</span><br />
</p>
This define enables compile-time function evaluation.<br />
This define is enabled by default.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_BUILD_X86_JIT</span><br />
</p>
This define enables x86 JiT executor.<br />
This define is enabled by default on platforms and compilers that support it.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_OPTIMIZE_X86</span><br />
</p>
This define enables x86 JiT executor code optimization.<br />
Code compilation speed is reduced greatly when JiT is in use and this flag is enabled.<br />
This define is enabled by default on platforms and compilers that support it, unless the <span class="comment">NULLC_ENABLE_C_TRANSLATION</span> is enabled.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_NO_EXECUTOR</span><br />
</p>
This define will build a compiler-only version of NULLC library.<br />
This define is disabled by default.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">#define</span> <span class="comment">NULLC_AUTOBINDING</span><br />
</p>
This define will enable an automatic function binding on Windows and Linux. More information in a topic <a href="#interop_bind">Binding functions to NULLC</a><br />
This define is enabled by default.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="init_term">1.2 Initialization and termination</a></h3>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcInit</span>(<span class="rword">const char</span>* importPath);<br />
</p>
Function initializes NULLC library with default allocation and deallocation functions.<br />
-<b>importPath</b> parameter sets that path in which the modules will be searched.<br />
Function is equivalent to <span class="func">nullcInitCustomAlloc</span>(<span class="comment">NULL</span>, <span class="comment">NULL</span>, importPath);<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcSetImportPath</span>(<span class="rword">const char</span>* importPath);<br />
</p>
This function will update the module import path.<br />
-<b>importPath</b> parameter sets that path in which the modules will be searched.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcInitCustomAlloc</span>(<span class="rword">void</span>* (<span class="comment">NCDECL</span> *allocFunc)(<span class="rword">int</span>), <span class="rword">void</span> (<span class="comment">NCDECL</span> *deallocFunc)(<span class="rword">void</span>*), <span class="rword">const char</span>* importPath);<br />
</p>
Function initializes NULLC library with specified allocation and deallocation functions.<br />
-<b>allocFunc</b> parameter sets the allocation function. It must be _cdecl function accepting one argument (allocation size) and returning pointer to allocated memory block.<br />
-<b>deallocFunc</b> parameter sets the deallocation function. It must be _cdecl function accepting one argument (pointer to a memory block to be freed). Return type must be void.<br />
-<b>importPath</b> parameter sets that path in which the modules will be searched.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcSetFileReadHandler</span>(<span class="rword">const void</span>* (<span class="comment">NCDECL</span> *fileLoadFunc)(<span class="rword">const char</span>* name, <span class="rword">unsigned int</span>* size, <span class="rword">int</span>* nullcShouldFreePtr));<br />
</p>
Function allows to set a handler for module file read operation. By default, fopen/ftell/fread/fclose function are used.<br />
-<b>fileLoadFunc</b> parameter sets the handler function. It must be _cdecl function accepting three arguments and returning pointer to a memory, where file contents are placed.<br />
<b>name</b> argument contains the path to a module.<br />
<b>size</b> argument is a pointer to a variable that should receive file size.<br />
<b>nullcShouldFreePtr</b> argument is a pointer to a variable that will tell whether NULLC should free memory to which return pointer points to.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcSetGlobalMemoryLimit</span>(<span class="rword">unsigned int</span> limit);<br />
</p>
Function sets the global memory limit and override the one set by <span class="comment">NULLC_DEFAULT_GLOBAL_MEMORY_LIMIT</span> define.<br />
- <b>limit</b> parameter is the new global memory limit.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcTerminate</span>();<br />
</p>
This function performs NULLC library deinitialization.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="exec_env">1.3 Execution settings and environment</a></h3>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcSetExecutor</span>(<span class="rword">unsigned int</span> id);
</p>
Change current executor.<br />
- <b>id</b> is executor ID. Can be either <span class="comment">NULLC_VM</span> or <span class="comment">NULLC_X86</span> (JiT).<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcSetJiTStack</span>(<span class="rword">void</span>* start, <span class="rword">void</span>* end, <span class="rword">unsigned int</span> flagMemoryAllocated);
</p>
Set memory range where JiT parameter stack will be placed.<br />
<br />
Windows specific:<br />
If <b>flagMemoryAllocated</b> is not set, executor will allocate memory itself using VirtualAlloc with base == <b>start</b>.<br />
Linux specific:<br />
If <b>flagMemoryAllocated</b> is not set, <b>start</b> parameter is ignored.<br />
<br />
When <b>flagMemoryAllocated</b> is not set, <b>end</b> can be set to <span class="comment">NULL</span>, meaning that x86 parameter stack can grow indefinitely.<br />
When <b>flagMemoryAllocated</b> is set, <b>start</b> and <b>end</b> should point to a user-allocated buffer. After a call it shouldn't be accessed or deallocated before a call to nullcTerminate or a call to nullcSetJiTStack with a different buffer.<br />
Default mode: <b>start</b> = <span class="real">0x20000000</span>, <b>end</b> = <span class="comment">NULL</span>, <b>flagMemoryAllocated</b> = false<br />
Function is available if <span class="comment">NULLC_BUILD_X86_JIT</span> is enabled.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcBindModuleFunction</span>(<span class="rword">const char</span>* module, <span class="rword">void</span> (<span class="comment">NCDECL</span> *ptr)(), <span class="rword">const char</span>* name, <span class="rword">int</span> index);
</p>
Function is used to bind unresolved module functions to external C functions.<br />
Read more abount C function binding in <a href="#interop_bind">interoperability</a> section.<br />
- <b>module</b> parameter is the module name (as in NULLC import expression), where the function will be searched.<br />
- <b>ptr</b> parameter is the pointer to C function (use a cast operation to bind functions with different types).<br />
- <b>name</b> parameter is the function name.<br />
- <b>index</b> parameter is the number of a function overload in order of definition in the source code.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcLoadModuleBySource</span>(<span class="rword">const char</span>* module, <span class="rword">const char</span>* code);
</p>
Builds module and saves its binary into binary cache.<br />
- <b>module</b> parameter is the module name as in NULLC import expression.<br />
- <b>code</b> parameter is the module source code.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcLoadModuleByBinary</span>(<span class="rword">const char</span>* module, <span class="rword">const char</span>* binary);
</p>
Loads module into binary cache.<br />
- <b>module</b> parameter is the module name as in NULLC import expression.<br />
- <b>binary</b> parameter is the module binary code.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="basic">1.4 Basic functions</a></h3>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcBuild</span>(<span class="rword">const char</span>* code);<br />
</p>
Compiles and links code.<br />
- <b>code</b> parameter is the module name as in NULLC import expression.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcRun</span>();<br />
</p>
Run global code.<br />
This function should be called at least once, before nullcRunFunction can be safely called, since it calculates global variable values.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcRunFunction</span>(<span class="rword">const char</span>* funcName, ...);<br />
</p>
Run function code.<br />
- <b>funcName</b> parameter is the name of the function to run. If it's <span class="comment">NULL</span>, the result is the same as calling nullcRun.<br />
- <b>...</b> arguments that will be passed into a function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">const char</span>* <span class="func">nullcGetResult</span>();<br />
<span class="rword">int</span> <span class="func">nullcGetResultInt</span>();<br />
<span class="rword">double</span> <span class="func">nullcGetResultDouble</span>();<br />
<span class="rword">long long</span> <span class="func">nullcGetResultLong</span>();<br />
</p>
Functions that retrieve last execution result of global code or function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">const char</span>* <span class="func">nullcGetLastError</span>();<br />
</p>
Function returns last error description.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="interact_func">1.5 Interaction functions</a></h3>
<div class="function">
<p class="code">
<span class="rword">void</span>* <span class="func">nullcAllocate</span>(<span class="rword">unsigned int</span> size);
</p>
Function allocates memory block that is managed by GC.<br />
- <b>size</b> parameter is an allocation size.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcThrowError</span>(<span class="rword">const char</span>* error, ...);
</p>
Function aborts NULLC program execution with a specified error (formatting as in printf function is supported).<br />
- <b>error</b> parameter is a format string.<br />
- <b>...</b> extra arguments.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcCallFunction</span>(<span class="rword">NULLCFuncPtr</span> ptr, ...);
</p>
Call function using NULLC function pointer with optional arguments.<br />
- <b>ptr</b> parameter is a pointer to NULLC function.<br />
- <b>...</b> arguments that will be passed into a function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcSetGlobal</span>(<span class="rword">const char</span>* name, <span class="rword">void</span>* data);
</p>
Set global variable value.<br />
- <b>name</b> parameter is a global variable name.<br />
- <b>data</b> parameter is a pointer to new variable data.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span>* <span class="func">nullcGetGlobal</span>(<span class="rword">const char</span>* name);
</p>
Get global variable value (can be modified).<br />
- <b>name</b> parameter is a global variable name.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcGetFunction</span>(<span class="rword">const char</span>* name, <span class="rword">NULLCFuncPtr</span>* func);
</p>
Get function pointer to use it in nullcCallFunction or to redirect it to some other function using nullcSetFunction.<br />
- <b>name</b> parameter is the function name.<br />
- <b>func</b> parameter is the pointer to NULLCFuncPtr struct that will receive pointer to function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcSetFunction</span>(<span class="rword">const char</span>* name, <span class="rword">NULLCFuncPtr</span> func);
</p>
Set function using function pointer to redirect function to another one.<br />
- <b>name</b> parameter is a global variable name.<br />
- <b>func</b> parameter is the NULLCFuncPtr struct that contains pointer to source function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcIsStackPointer</span>(<span class="rword">void</span>* ptr);
</p>
Function returns 1 if passed pointer points to NULLC stack; otherwise, the return value is 0.<br />
- <b>ptr</b> parameter is a pointer to check.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcIsManagedPointer</span>(<span class="rword">void</span>* ptr);
</p>
Function returns 1 if passed pointer points to a memory managed by NULLC GC; otherwise, the return value is 0.<br />
- <b>ptr</b> parameter is a pointer to check.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="special">1.7 Special modules</a></h3>
Some modules heavily rely on internal NULLC structure, and because of that, they are initialized through NULLC interface.<br />
<div class="function">
<p class="code">
<span class="rword">int</span> <span class="func">nullcInitTypeinfoModule</span>();
</p>
Function initializes std.typeinfo module.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">int</span> <span class="func">nullcInitDynamicModule</span>();
</p>
Function initializes std.dynamic module.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="extended">1.8 Extended functions</a></h3>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcCompile</span>(<span class="rword">const char</span>* code);
</p>
Function compiles the source code.<br />
- <b>code</b> parameter is a pointer to a string with source code.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">unsigned int</span> <span class="func">nullcGetBytecode</span>(<span class="rword">char</span>** bytecode);
</p>
Function is used to get bytecode for compiled source code.<br />
Bytecode can be later linked with nullcLinkCode and executed.<br />
- <b>bytecode</b> parameter is a pointer to pointer that will receive the bytecode. Memory must be freed by user.<br />
Function returns the size of the bytecode.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">unsigned int</span> <span class="func">nullcGetBytecodeNoCache</span>(<span class="rword">char</span>** bytecode);
</p>
This function is similar to nullcGetBytecode, with one exception:<br />
After bytecode is retrieved by nullcGetBytecode, it is put into bytecode cache as "__last" module that can be imported later to implement advanced features like dynamic code evaluation (see std.dynamic).<br />
If you wish that "__last" module bytecode is not changed, you should use this function.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcClean</span>();
</p>
Clean all accumulated bytecode from linker.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">nullres</span> <span class="func">nullcLinkCode</span>(<span class="rword">const char</span>* bytecode);
</p>
Link new chunk of bytecode.<br />
Type or function redefinition generates an error.<br />
Global variables with the same name are handled silently.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcSaveListing</span>(<span class="rword">const char</span>* fileName);
</p>
This function saves disassembly of last compiled code into file.<br />
</div>
<div class="function">
<p class="code">
<span class="rword">void</span> <span class="func">nullcTranslateToC</span>(<span class="rword">const char</span>* fileName, <span class="rword">const char</span>* mainName);
</p>
This function saved analog of C++ code of last compiled code into file.<br />
Function works only if <span class="comment">NULLC_ENABLE_C_TRANSLATION</span> is defined.<br />
</div>
</div>
<hr />
<div class="topic">
<h3><a name="debug">1.9 Debug functions</a></h3>
</div>
<hr />
<h2 align="center">2. Interoperability with C code</h2>
<div class="topic">
<h3><a name="interop_bind">2.1 Binding functions to NULLC</a></h3>
Only functions with cdecl calling convention can be binded to NULLC.<br />
<br />
All basic numeric types are equal in representation to C++ types, except for "long" type which corresponds to 64bit "long long" type in C++.<br />
NULLC reference types are simple pointers.<br />
NULLC array with implicit size corresponds to NULLCArray struct.<br />
NULLC "auto ref" type corresponds to NULLCRef struct.<br />
NULLC function pointers correspond to NULLCFuncPtr struct.<br />
NULLC "auto[]" type corresponds to NULLCAutoArray struct.<br />
<br />
It is not recommended to pass NULLC classes and explicitly-sized arrays by value.<br />
<br />
If you want to bind class member function, it must accept pointer to class type as the <b>last</b> parameter.<br />
<br />
NULLC classes can be transformed into C structures by applying the same transformations used for function arguments.<br />
A care must be taken for class member alignment: members are aligned to their default align values, <b>but no more than 4 bytes</b> (see Basic types topic in language reference).<br />
So it is recommended to wrap C struct definition into a "#pragma pack(push, 4) ... #pragma pack(pop)".<br />
<br />
When binding a class member function, add "class::" before the function name (that's two ':' instead of one you see in externally defined member function).<br />
<br />
If NULLC_AUTOBINDING define is enabled, you can write NULLC_BIND before your functions and NULLC linker will bind them automatically.<br />
This works only for plain functions and not for class member functions.<br />
Under gcc, you must build NULLC with "-ldl" flag and build your application with "-rdynamic" and "-ldl" flags, in order for auto binding to work.<br />
</div>
<hr />
</body>
</html>