aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/embryo/src/lib/Embryo.h
diff options
context:
space:
mode:
Diffstat (limited to 'libraries/embryo/src/lib/Embryo.h')
-rw-r--r--libraries/embryo/src/lib/Embryo.h901
1 files changed, 0 insertions, 901 deletions
diff --git a/libraries/embryo/src/lib/Embryo.h b/libraries/embryo/src/lib/Embryo.h
deleted file mode 100644
index 4003f6b..0000000
--- a/libraries/embryo/src/lib/Embryo.h
+++ /dev/null
@@ -1,901 +0,0 @@
1/**
2@brief Embryo Library
3
4These routines are used for Embryo.
5
6@mainpage Embryo Library Documentation
7
8@image html e_big.png
9
10@version 1.0.0
11@author Carsten Haitzler <raster\@rasterman.com>
12@author Compuphase http://www.compuphase.com
13@date 2004-2012
14
15@section intro What is Embryo?
16
17Embryo is a tiny library designed to interpret limited Small programs
18compiled by the included compiler, @c embryo_cc. It is mostly a cleaned
19up and smaller version of the original Small abstract machine. The
20compiler is mostly untouched.
21
22Small was renamed to Pawn.
23For more information about the Pawn language, see
24@htmlonly <a href=http://www.compuphase.com/pawn/pawn.htm>Pawn</a>
25@endhtmlonly
26@latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly
27For the basics about the Small language, see @ref Small_Page.
28
29@section How_to_Use How to Use Embryo?
30
31To use Embryo in your code, you need to do at least the following:
32
33@li Include @ref Embryo.h.
34@li Load the Embryo program using one of the
35 @ref Embryo_Program_Creation_Group.
36@li Set up the native calls with @ref embryo_program_native_call_add.
37@li Create a virtual machine with @ref embryo_program_vm_push.
38@li Then run the program with @ref embryo_program_run.
39
40@todo Clean up compiler code.
41@todo Proper overview of the operation of the interpreter, that is how
42 the heap, stack, virtual machines, etc fit together.
43
44@page Small_Page Brief Introduction to Small
45
46This section describes the basics of Small, as compiled and interpreted
47with Embryo.
48
49This summary assumes that you are familar with C. For a full list of
50differences between C and Small, again, see the full documentation.
51
52@section Small_Variables_Section Variables
53
54@subsection Small_Type_Subsection Types
55
56There is only one type, known as the "cell", which can hold an integer.
57
58@subsection Small_Scope_Subsection Scope
59
60The scope and usage of a variable depends on its declaration.
61
62@li A local variable is normally declared with the @c new keyword. E.g.
63 @code new variable @endcode
64@li A static function variable is defined within a function with the
65 @c static keyword.
66@li A global static variable is one that is only available within the
67 file it was declared in. Again, use the @c static keyword, but outside
68 of any function.
69@li A stock variable is one that may not be compiled into a program if it
70 is not used. It is declared using @c stock.
71@li A public variable is one that can be read by the host program using
72 @ref embryo_program_variable_find. It is declared using @c public
73 keyword.
74
75Remember that the keywords above are to be used on their own. That is,
76for example: @code public testvar @endcode not:
77@code new public testvar @endcode
78
79@subsection Small_Constants_Subsection Constants
80
81You can declare constants in two ways:
82@li Using the preprocessor macro @c \#define.
83@li By inserting @c const between the keyword and variable name of a
84 variable declaration. For example, to declare the variable @c var1
85 constant, you type @code new const var1 = 2 @endcode Now @c var1
86 cannot be changed.
87
88@subsection Small_Arrays_Subsection Arrays
89
90To declare an array, append square brackets to the end of the variable
91name. The following examples show how to declare arrays. Note the
92use of the ellipsis operator, which bases the array based on the last two
93declared values:
94
95@code
96new msg[] = "A message."
97new ints[] = {1, 3, 4}
98new ints2[20] = {1, 3} // All other elements 0.
99new ints3[10] = {1, ... } // All elements = 1
100new ints4[10] = {10, 20, ... } // Elements = 10 -> 100.
101 // The difference can be negative.
102new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}}
103@endcode
104
105@note Array initialisers need to be constant.
106
107@section Small_Func_Calls_Section Function Calls
108
109A typical function declaration is as follows:
110
111@code
112testfunc(param) {
113 // Do something ...
114 // over a couple of lines.
115}
116@endcode
117
118You can pass by reference. That is, the parameter you pass is changed
119outside of the function. For example:
120
121@code
122testfunc(&param) {
123 param = 10
124 // The passed variable will be set to 10 outside of the function.
125}
126@endcode
127
128To pass an array:
129
130@code
131testfunc(param[]) {
132 // Do something to the array
133}
134@endcode
135
136@note Arrays are passed by reference.
137
138@section Small_Control_Subsection Control Structures.
139
140Small has the following control structures, which similar to their C
141counterparts:
142@li @code if (expression) statement1 else statement2 @endcode
143@li @code switch (expression) {
144 case 0:
145 statement1 // Can only be one statement. Look Ma, no breaks!
146 case 1..3: // For values between 1 and 3 inclusive.
147 statement2
148 default: // Optional
149 statement3
150}
151@endcode
152@li @code while(expression) statement @endcode
153@li @code do statement while (expression) @endcode
154@li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode
155
156@section Small_Preprocessor_Section Preprocessor
157
158The following preprocessor directives are available:
159@li @code #assert constant_expression @endcode
160@li @code #define pattern replacement @endcode
161@li @code #define pattern(%1,%2,...) replacement @endcode
162@li @code #include filename @endcode
163@li @code #if constant_expression
164 // Various bits of code
165#else
166 // Other bits of code
167#endif
168@endcode
169@li @code #undef pattern @endcode
170
171
172@page Available_Native_Calls_Page Available Calls
173
174Embryo provides a minimal set of native calls that can be used within
175any Embryo script. Those calls are detailed here.
176
177@note Some of the "core" functions here are also described in the full
178 Small documentation given
179
180@todo Finish this section.
181
182@section Args_ANC_Section Argument Functions
183
184@subsection Numargs_Desc numargs
185
186Returns the number of arguments passed to a function. Useful
187when dealing with variable argument lists.
188
189@subsection Getargs_Desc getarg(arg, index=0)
190
191Retrieves the argument number @c arg. If the argument is an array,
192use @c index to specify the index of the array to return.
193
194@subsection Setargs_Desc setargs(arg, index=0, value)
195
196Sets the argument number @c arg to the given @c arg. @c index specifies
197the index of @c arg to set if @c arg is an array.
198
199@section String_ANC_Section String Functions
200
201Functions that work on strings.
202
203@subsection Atoi_Desc atoi
204
205Translates an number in string form into an integer.
206
207@subsection Fnmatch_Desc fnmatch
208
209Buggered if I know what this does?
210
211@subsection Strcmp_Desc strcmp
212
213String comparing function.
214
215
216@section Float_ANC_Section Float Functions
217
218@subsection Float_Desc float
219
220@subsection Atof_Desc atof
221
222@subsection Float_Mul_Desc float_mul
223
224@subsection Float_Div_Desc float_div
225
226@subsection Float_Add_Desc float_add
227
228@subsection Float_Sub_Desc float_sub
229
230@subsection Fract_Desc fract
231
232@subsection Round_Desc round
233
234@subsection Float_Cmp_Desc float_cmp
235
236@subsection Sqrt_Desc sqrt
237
238@subsection Pow_Desc pow
239
240@subsection Log_Desc log
241
242@subsection Sin_Desc sin
243
244@subsection Cos_Desc cos
245
246@subsection Tan_Desc tan
247
248@subsection Abs_Desc abs
249
250Returns the absolute value of the given float.
251
252@section Time_ANC_Section Time Functions
253
254@subsection Seconds_Desc seconds()
255
256@subsection Date_Desc date
257
258
259@section Rand_ANC_Section Random Functions
260
261@subsection Rand_Desc rand()
262
263Returns a random integer.
264
265@subsection Randf_Desc randf()
266
267Returns a random float.
268
269@file Embryo.h
270@brief Embryo virtual machine library.
271
272This file includes the routines needed for Embryo library interaction.
273This is the @e only file you need to include.
274
275*/
276
277// The following definitions are in Embryo.h, but I did not want to
278// mess up the formatting of the file
279
280/**
281 @def EMBRYO_FUNCTION_NONE
282 An invalid/non-existent function.
283*/
284
285/**
286 @def EMBRYO_FUNCTION_MAIN
287 Start at program entry point. For use with @ref embryo_program_run.
288*/
289
290/**
291 @def EMBRYO_FUNCTION_CONT
292 Continue from last address. For use with @ref embryo_program_run.
293*/
294
295/**
296 @def EMBRYO_PROGRAM_OK
297 Program was run successfully.
298*/
299
300/**
301 @def EMBRYO_PROGRAM_SLEEP
302 The program's execution was interrupted by a Small @c sleep command.
303*/
304
305/**
306 @def EMBRYO_PROGRAM_FAIL
307 An error in the program caused it to fail.
308*/
309
310#ifndef _EMBRYO_H
311#define _EMBRYO_H
312
313#ifdef EAPI
314# undef EAPI
315#endif
316
317#ifdef _WIN32
318# ifdef EFL_EMBRYO_BUILD
319# ifdef DLL_EXPORT
320# define EAPI __declspec(dllexport)
321# else
322# define EAPI
323# endif /* ! DLL_EXPORT */
324# else
325# define EAPI __declspec(dllimport)
326# endif /* ! EFL_EMBRYO_BUILD */
327#else
328# ifdef __GNUC__
329# if __GNUC__ >= 4
330# define EAPI __attribute__ ((visibility("default")))
331# else
332# define EAPI
333# endif
334# else
335# define EAPI
336# endif
337#endif /* ! _WIN32 */
338
339#ifdef __cplusplus
340extern "C" {
341#endif
342
343#define EMBRYO_VERSION_MAJOR 1
344#define EMBRYO_VERSION_MINOR 2
345
346 typedef struct _Embryo_Version
347 {
348 int major;
349 int minor;
350 int micro;
351 int revision;
352 } Embryo_Version;
353
354 EAPI extern Embryo_Version *embryo_version;
355
356 /* potential error values */
357 typedef enum _Embryo_Error
358 {
359 EMBRYO_ERROR_NONE,
360 /* reserve the first 15 error codes for exit codes of the abstract machine */
361 EMBRYO_ERROR_EXIT, /** Forced exit */
362 EMBRYO_ERROR_ASSERT, /** Assertion failed */
363 EMBRYO_ERROR_STACKERR, /** Stack/heap collision */
364 EMBRYO_ERROR_BOUNDS, /** Index out of bounds */
365 EMBRYO_ERROR_MEMACCESS, /** Invalid memory access */
366 EMBRYO_ERROR_INVINSTR, /** Invalid instruction */
367 EMBRYO_ERROR_STACKLOW, /** Stack underflow */
368 EMBRYO_ERROR_HEAPLOW, /** Heap underflow */
369 EMBRYO_ERROR_CALLBACK, /** No callback, or invalid callback */
370 EMBRYO_ERROR_NATIVE, /** Native function failed */
371 EMBRYO_ERROR_DIVIDE, /** Divide by zero */
372 EMBRYO_ERROR_SLEEP, /** Go into sleepmode - code can be restarted */
373
374 EMBRYO_ERROR_MEMORY = 16, /** Out of memory */
375 EMBRYO_ERROR_FORMAT, /** Invalid file format */
376 EMBRYO_ERROR_VERSION, /** File is for a newer version of the Embryo_Program */
377 EMBRYO_ERROR_NOTFOUND, /** Function not found */
378 EMBRYO_ERROR_INDEX, /** Invalid index parameter (bad entry point) */
379 EMBRYO_ERROR_DEBUG, /** Debugger cannot run */
380 EMBRYO_ERROR_INIT, /** Embryo_Program not initialized (or doubly initialized) */
381 EMBRYO_ERROR_USERDATA, /** Unable to set user data field (table full) */
382 EMBRYO_ERROR_INIT_JIT, /** Cannot initialize the JIT */
383 EMBRYO_ERROR_PARAMS, /** Parameter error */
384 EMBRYO_ERROR_DOMAIN, /** Domain error, expression result does not fit in range */
385 } Embryo_Error;
386
387 /* program run return values */
388 typedef enum _Embryo_Status
389 {
390 EMBRYO_PROGRAM_FAIL = 0,
391 EMBRYO_PROGRAM_OK = 1,
392 EMBRYO_PROGRAM_SLEEP = 2,
393 EMBRYO_PROGRAM_BUSY = 3,
394 EMBRYO_PROGRAM_TOOLONG = 4
395 } Embryo_Status;
396
397 typedef unsigned int Embryo_UCell;
398 typedef int Embryo_Cell;
399 /** An invalid cell reference */
400#define EMBRYO_CELL_NONE 0x7fffffff
401
402 typedef struct _Embryo_Program Embryo_Program;
403 typedef int Embryo_Function;
404 /* possible function type values that are enumerated */
405#define EMBRYO_FUNCTION_NONE 0x7fffffff /* An invalid/non existent function */
406#define EMBRYO_FUNCTION_MAIN -1 /* Start at program entry point */
407#define EMBRYO_FUNCTION_CONT -2 /* Continue from last address */
408
409 typedef union
410 {
411 float f;
412 Embryo_Cell c;
413 } Embryo_Float_Cell;
414
415#if defined _MSC_VER || defined __SUNPRO_C
416/** Float to Embryo_Cell */
417# define EMBRYO_FLOAT_TO_CELL(f) (((Embryo_Float_Cell *)&(f))->c)
418/** Embryo_Cell to float */
419# define EMBRYO_CELL_TO_FLOAT(c) (((Embryo_Float_Cell *)&(c))->f)
420#else
421/** Float to Embryo_Cell */
422# define EMBRYO_FLOAT_TO_CELL(f) ((Embryo_Float_Cell) f).c
423/** Embryo_Cell to float */
424# define EMBRYO_CELL_TO_FLOAT(c) ((Embryo_Float_Cell) c).f
425#endif
426
427 /**
428 * @defgroup Embryo_Library_Group Library Maintenance Functions
429 *
430 * Functions that start up and shutdown the Embryo library.
431 */
432
433
434/**
435 * Initialises the Embryo library.
436 * @return The number of times the library has been initialised without being
437 * shut down.
438 * @ingroup Embryo_Library_Group
439 */
440EAPI int embryo_init(void);
441
442/**
443 * Shuts down the Embryo library.
444 * @return The number of times the library has been initialised without being
445 * shutdown.
446 * @ingroup Embryo_Library_Group
447 */
448EAPI int embryo_shutdown(void);
449
450 /**
451 * @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions
452 *
453 * Functions that set up programs, and destroy them.
454 */
455
456/**
457 * Creates a new Embryo program, with bytecode data that can be freed.
458 * @param data Pointer to the bytecode of the program.
459 * @param size Number of bytes of bytecode.
460 * @return A new Embryo program.
461 * @ingroup Embryo_Program_Creation_Group
462 */
463EAPI Embryo_Program *embryo_program_new(void *data, int size);
464
465/**
466 * Creates a new Embryo program, with bytecode data that cannot be
467 * freed.
468 * @param data Pointer to the bytecode of the program.
469 * @param size Number of bytes of bytecode.
470 * @return A new Embryo program.
471 * @ingroup Embryo_Program_Creation_Group
472 */
473EAPI Embryo_Program *embryo_program_const_new(void *data, int size);
474
475/**
476 * Creates a new Embryo program based on the bytecode data stored in the
477 * given file.
478 * @param file Filename of the given file.
479 * @return A new Embryo program.
480 * @ingroup Embryo_Program_Creation_Group
481 */
482EAPI Embryo_Program *embryo_program_load(const char *file);
483
484/**
485 * Frees the given Embryo program.
486 * @param ep The given program.
487 * @ingroup Embryo_Program_Creation_Group
488 */
489EAPI void embryo_program_free(Embryo_Program *ep);
490
491/**
492 * Adds a native program call to the given Embryo program.
493 * @param ep The given Embryo program.
494 * @param name The name for the call used in the script.
495 * @param func The function to use when the call is made.
496 * @ingroup Embryo_Func_Group
497 */
498
499/**
500 * @defgroup Embryo_Func_Group Function Functions
501 *
502 * Functions that deal with Embryo program functions.
503 */
504EAPI void embryo_program_native_call_add(Embryo_Program *ep, const char *name, Embryo_Cell (*func) (Embryo_Program *ep, Embryo_Cell *params));
505
506/**
507 * Resets the current virtual machine session of the given program.
508 * @param ep The given program.
509 * @ingroup Embryo_Program_VM_Group
510 */
511
512/**
513 * @defgroup Embryo_Program_VM_Group Virtual Machine Functions
514 *
515 * Functions that deal with creating and destroying virtual machine sessions
516 * for a given program.
517 *
518 * A given embryo program can have multiple virtual machine sessions running.
519 * This is useful when you have a native call that in turn calls a function in
520 * the embryo program. The native call can start a new virtual machine
521 * session to run the function it needs. Once completed, the session can be
522 * popped off the program's stack, and the native call can return its value
523 * to the old session.
524 *
525 * A new virtual machine session is created by pushing a new virtual machine
526 * onto the session stack of a program using @ref embryo_program_vm_push.
527 * The current virtual machine session can be destroyed by calling
528 * @ref embryo_program_vm_pop.
529 */
530EAPI void embryo_program_vm_reset(Embryo_Program *ep);
531
532/**
533 * Starts a new virtual machine session for the given program.
534 *
535 * See @ref Embryo_Program_VM_Group for more information about how this works.
536 *
537 * @param ep The given program.
538 * @ingroup Embryo_Program_VM_Group
539 */
540EAPI void embryo_program_vm_push(Embryo_Program *ep);
541
542/**
543 * Frees the current virtual machine session associated with the given program.
544 *
545 * See @ref Embryo_Program_VM_Group for more information about how this works.
546 * Note that you will need to retrieve any return data or data on the stack
547 * before you pop.
548 *
549 * @param ep The given program.
550 * @ingroup Embryo_Program_VM_Group
551 */
552EAPI void embryo_program_vm_pop(Embryo_Program *ep);
553
554/**
555 * Ensures that the given unsigned short integer is in the small
556 * endian format.
557 * @param v Pointer to the given integer.
558 * @ingroup Embryo_Swap_Group
559 */
560
561/**
562 * @defgroup Embryo_Swap_Group Byte Swapping Functions
563 *
564 * Functions that are used to ensure that integers passed to the
565 * virtual machine are in small endian format. These functions are
566 * used to ensure that the virtual machine operates correctly on big
567 * endian machines.
568 */
569EAPI void embryo_swap_16(unsigned short *v);
570
571/**
572 * Ensures that the given unsigned integer is in the small endian
573 * format.
574 * @param v Pointer to the given integer.
575 * @ingroup Embryo_Swap_Group
576 */
577EAPI void embryo_swap_32(unsigned int *v);
578
579/**
580 * Returns the function in the given program with the given name.
581 * @param ep The given program.
582 * @param name The given function name.
583 * @return The function if successful. Otherwise, @c EMBRYO_FUNCTION_NONE.
584 * @ingroup Embryo_Func_Group
585 */
586EAPI Embryo_Function embryo_program_function_find(Embryo_Program *ep, const char *name);
587
588/**
589 * Retrieves the location of the public variable in the given program
590 * with the given name.
591 * @param ep The given program.
592 * @param name The given name.
593 * @return The address of the variable if found. @c EMBRYO_CELL_NONE
594 * otherwise.
595 * @ingroup Embryo_Public_Variable_Group
596 */
597
598/**
599 * @defgroup Embryo_Public_Variable_Group Public Variable Access Functions
600 *
601 * In an Embryo program, a global variable can be declared public, as
602 * described in @ref Small_Scope_Subsection. The functions here allow
603 * the host program to access these public variables.
604 */
605EAPI Embryo_Cell embryo_program_variable_find(Embryo_Program *ep, const char *name);
606
607/**
608 * Retrieves the number of public variables in the given program.
609 * @param ep The given program.
610 * @return The number of public variables.
611 * @ingroup Embryo_Public_Variable_Group
612 */
613EAPI int embryo_program_variable_count_get(Embryo_Program *ep);
614
615/**
616 * Retrieves the location of the public variable in the given program
617 * with the given identifier.
618 * @param ep The given program.
619 * @param num The identifier of the public variable.
620 * @return The virtual machine address of the variable if found.
621 * @c EMBRYO_CELL_NONE otherwise.
622 * @ingroup Embryo_Public_Variable_Group
623 */
624EAPI Embryo_Cell embryo_program_variable_get(Embryo_Program *ep, int num);
625
626/**
627 * Sets the error code for the given program to the given code.
628 * @param ep The given program.
629 * @param error The given error code.
630 * @ingroup Embryo_Error_Group
631 */
632
633/**
634 * @defgroup Embryo_Error_Group Error Functions
635 *
636 * Functions that set and retrieve error codes in Embryo programs.
637 */
638EAPI void embryo_program_error_set(Embryo_Program *ep, Embryo_Error error);
639
640/**
641 * Retrieves the current error code for the given program.
642 * @param ep The given program.
643 * @return The current error code.
644 * @ingroup Embryo_Error_Group
645 */
646EAPI Embryo_Error embryo_program_error_get(Embryo_Program *ep);
647
648/**
649 * Sets the data associated to the given program.
650 * @param ep The given program.
651 * @param data New bytecode data.
652 * @ingroup Embryo_Program_Data_Group
653 */
654
655/**
656 * @defgroup Embryo_Program_Data_Group Program Data Functions
657 *
658 * Functions that set and retrieve data associated with the given
659 * program.
660 */
661EAPI void embryo_program_data_set(Embryo_Program *ep, void *data);
662
663/**
664 * Retrieves the data associated to the given program.
665 * @param ep The given program.
666 * @ingroup Embryo_Program_Data_Group
667 */
668EAPI void *embryo_program_data_get(Embryo_Program *ep);
669
670/**
671 * Retrieves a string describing the given error code.
672 * @param error The given error code.
673 * @return String describing the given error code. If the given code is not
674 * known, the string "(unknown)" is returned.
675 * @ingroup Embryo_Error_Group
676 */
677EAPI const char *embryo_error_string_get(Embryo_Error error);
678
679/**
680 * Retrieves the length of the string starting at the given cell.
681 * @param ep The program the cell is part of.
682 * @param str_cell Pointer to the first cell of the string.
683 * @return The length of the string. @c 0 is returned if there is an error.
684 * @ingroup Embryo_Data_String_Group
685 */
686
687/**
688 * @defgroup Embryo_Data_String_Group Embryo Data String Functions
689 *
690 * Functions that operate on strings in the memory of a virtual machine.
691 */
692EAPI int embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell);
693
694/**
695 * Copies the string starting at the given cell to the given buffer.
696 * @param ep The program the cell is part of.
697 * @param str_cell Pointer to the first cell of the string.
698 * @param dst The given buffer.
699 * @ingroup Embryo_Data_String_Group
700 */
701EAPI void embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst);
702
703/**
704 * Copies string in the given buffer into the virtual machine memory
705 * starting at the given cell.
706 * @param ep The program the cell is part of.
707 * @param src The given buffer.
708 * @param str_cell Pointer to the first cell to copy the string to.
709 * @ingroup Embryo_Data_String_Group
710 */
711EAPI void embryo_data_string_set(Embryo_Program *ep, const char *src, Embryo_Cell *str_cell);
712
713/**
714 * Retreives a pointer to the address in the virtual machine given by the
715 * given cell.
716 * @param ep The program whose virtual machine address is being queried.
717 * @param addr The given cell.
718 * @return A pointer to the cell at the given address.
719 * @ingroup Embryo_Data_String_Group
720 */
721EAPI Embryo_Cell *embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr);
722
723/**
724 * Increases the size of the heap of the given virtual machine by the given
725 * number of Embryo_Cells.
726 * @param ep The program with the given virtual machine.
727 * @param cells The given number of Embryo_Cells.
728 * @return The address of the new memory region on success.
729 * @c EMBRYO_CELL_NONE otherwise.
730 * @ingroup Embryo_Heap_Group
731 */
732
733/**
734 * @defgroup Embryo_Heap_Group Heap Functions
735 *
736 * The heap is an area of memory that can be allocated for program
737 * use at runtime. The heap functions here change the amount of heap
738 * memory available.
739 */
740EAPI Embryo_Cell embryo_data_heap_push(Embryo_Program *ep, int cells);
741
742/**
743 * Decreases the size of the heap of the given virtual machine down to the
744 * given size.
745 * @param ep The program with the given virtual machine.
746 * @param down_to The given size.
747 * @ingroup Embryo_Heap_Group
748 */
749EAPI void embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to);
750
751/**
752 * Returns the number of virtual machines are running for the given program.
753 * @param ep The given program.
754 * @return The number of virtual machines running.
755 * @ingroup Embryo_Run_Group
756 */
757
758/**
759 * @defgroup Embryo_Run_Group Program Run Functions
760 *
761 * Functions that are involved in actually running functions in an
762 * Embryo program.
763 */
764EAPI int embryo_program_recursion_get(Embryo_Program *ep);
765
766/**
767 * Runs the given function of the given Embryo program in the current
768 * virtual machine. The parameter @p fn can be found using
769 * @ref embryo_program_function_find.
770 *
771 * @note For Embryo to be able to run a function, it must have been
772 * declared @c public in the Small source code.
773 *
774 * @param ep The given program.
775 * @param fn The given function. Normally "main", in which case the
776 * constant @c EMBRYO_FUNCTION_MAIN can be used.
777 * @return @c EMBRYO_PROGRAM_OK on success. @c EMBRYO_PROGRAM_SLEEP if the
778 * program is halted by the Small @c sleep call.
779 * @c EMBRYO_PROGRAM_FAIL if there is an error.
780 * @c EMBRYO_PROGRAM_TOOLONG if the program executes for longer than
781 * it is allowed to in abstract machine instruction count.
782 * @ingroup Embryo_Run_Group
783 */
784EAPI Embryo_Status embryo_program_run(Embryo_Program *ep, Embryo_Function func);
785
786/**
787 * Retreives the return value of the last called function of the given
788 * program.
789 * @param ep The given program.
790 * @return An Embryo_Cell representing the return value of the function
791 * that was last called.
792 * @ingroup Embryo_Run_Group
793 */
794EAPI Embryo_Cell embryo_program_return_value_get(Embryo_Program *ep);
795
796/**
797 * Sets the maximum number of abstract machine cycles any given program run
798 * can execute before being put to sleep and returning.
799 *
800 * @param ep The given program.
801 * @param max The number of machine cycles as a limit.
802 *
803 * This sets the maximum number of abstract machine (virtual machine)
804 * instructions that a single run of an embryo function (even if its main)
805 * can use before embryo embryo_program_run() reutrns with the value
806 * EMBRYO_PROGRAM_TOOLONG. If the function fully executes within this number
807 * of cycles, embryo_program_run() will return as normal with either
808 * EMBRYO_PROGRAM_OK, EMBRYO_PROGRAM_FAIL or EMBRYO_PROGRAM_SLEEP. If the
809 * run exceeds this instruction count, then EMBRYO_PROGRAM_TOOLONG will be
810 * returned indicating the program exceeded its run count. If the app wishes
811 * to continue running this anyway - it is free to process its own events or
812 * whatever it wants and continue the function by calling
813 * embryo_program_run(program, EMBRYO_FUNCTION_CONT); which will start the
814 * run again until the instruction count is reached. This can keep being done
815 * to allow the calling program to still be able to control things outside the
816 * embryo function being called. If the maximum run cycle count is 0 then the
817 * program is allowed to run forever only returning when it is done.
818 *
819 * It is important to note that abstract machine cycles are NOT the same as
820 * the host machine cpu cycles. They are not fixed in runtime per cycle, so
821 * this is more of a helper tool than a way to HARD-FORCE a script to only
822 * run for a specific period of time. If the cycle count is set to something
823 * low like 5000 or 1000, then every 1000 (or 5000) cycles control will be
824 * returned to the calling process where it can check a timer to see if a
825 * physical runtime limit has been elapsed and then abort running further
826 * assuming a "runaway script" or keep continuing the script run. This
827 * limits resolution to only that many cycles which do not take a determined
828 * amount of time to execute, as this varies from cpu to cpu and also depends
829 * on how loaded the system is. Making the max cycle run too low will
830 * impact performance requiring the abstract machine to do setup and teardown
831 * cycles too often comapred to cycles actually executed.
832 *
833 * Also note it does NOT include nested abstract machines. IF this abstract
834 * machine run calls embryo script that calls a native function that in turn
835 * calls more embryo script, then the 2nd (and so on) levels are not included
836 * in this run count. They can set their own max instruction count values
837 * separately.
838 *
839 * The default max cycle run value is 0 in any program until set with this
840 * function.
841 *
842 * @ingroup Embryo_Run_Group
843 */
844EAPI void embryo_program_max_cycle_run_set(Embryo_Program *ep, int max);
845
846/**
847 * Retreives the maximum number of abstract machine cycles a program is allowed
848 * to run.
849 * @param ep The given program.
850 * @return The number of cycles a run cycle is allowed to run for this
851 * program.
852 *
853 * This returns the value set by embryo_program_max_cycle_run_set(). See
854 * embryo_program_max_cycle_run_set() for more information.
855 *
856 * @ingroup Embryo_Run_Group
857 */
858EAPI int embryo_program_max_cycle_run_get(Embryo_Program *ep);
859
860/**
861 * Pushes an Embryo_Cell onto the function stack to use as a parameter for
862 * the next function that is called in the given program.
863 * @param ep The given program.
864 * @param cell The Embryo_Cell to push onto the stack.
865 * @return @c 1 if successful. @c 0 otherwise.
866 * @ingroup Embryo_Parameter_Group
867 */
868
869/**
870 * @defgroup Embryo_Parameter_Group Function Parameter Functions
871 *
872 * Functions that set parameters for the next function that is called.
873 */
874EAPI int embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell);
875
876/**
877 * Pushes a string onto the function stack to use as a parameter for the
878 * next function that is called in the given program.
879 * @param ep The given program.
880 * @param str The string to push onto the stack.
881 * @return @c 1 if successful. @c 0 otherwise.
882 * @ingroup Embryo_Parameter_Group
883 */
884EAPI int embryo_parameter_string_push(Embryo_Program *ep, const char *str);
885
886/**
887 * Pushes an array of Embryo_Cells onto the function stack to be used as
888 * parameters for the next function that is called in the given program.
889 * @param ep The given program.
890 * @param cells The array of Embryo_Cells.
891 * @param num The number of cells in @p cells.
892 * @return @c 1 if successful. @c 0 otherwise.
893 * @ingroup Embryo_Parameter_Group
894 */
895EAPI int embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num);
896
897#ifdef __cplusplus
898}
899#endif
900
901#endif
generated by cgit v1.1 at 2024-10-30 10:48:22 +0000