src/lib/Embryo.h

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