src/lib/Embryo.h

   1 /**
   2 @brief Embryo Library
   3
   4 These routines are used for Embryo.
   5
   6 @mainpage Embryo Library Documentation
   7
   8 @image html  e_big.png
   9
  10 @version 1.2.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
  17 Embryo is a tiny library designed to interpret limited Small programs
  18 compiled by the included compiler, @c embryo_cc.  It is mostly a cleaned
  19 up and smaller version of the original Small abstract machine.  The
  20 compiler is mostly untouched.
  21
  22 Small was renamed to Pawn.
  23 For 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
  27 For the basics about the Small language, see @ref Small_Page.
  28
  29 @section How_to_Use How to Use Embryo?
  30
  31 To 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
  46 This section describes the basics of Small, as compiled and interpreted
  47 with Embryo.
  48
  49 This summary assumes that you are familar with C.  For a full list of
  50 differences between C and Small, again, see the full documentation.
  51
  52 @section Small_Variables_Section Variables
  53
  54 @subsection Small_Type_Subsection Types
  55
  56 There is only one type, known as the "cell", which can hold an integer.
  57
  58 @subsection Small_Scope_Subsection Scope
  59
  60 The 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
  75 Remember that the keywords above are to be used on their own.  That is,
  76 for example: @code public testvar @endcode not:
  77 @code new public testvar @endcode
  78
  79 @subsection Small_Constants_Subsection Constants
  80
  81 You 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
  90 To declare an array, append square brackets to the end of the variable
  91 name.  The following examples show how to declare arrays.  Note the
  92 use of the ellipsis operator, which bases the array based on the last two
  93 declared values:
  94
  95 @code
  96 new msg[] = "A message."
  97 new ints[] = {1, 3, 4}
  98 new ints2[20] = {1, 3}         // All other elements 0.
  99 new ints3[10] = {1, ... }      // All elements = 1
 100 new ints4[10] = {10, 20, ... } // Elements = 10 -> 100.
 101                                // The difference can be negative.
 102 new 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
 109 A typical function declaration is as follows:
 110
 111 @code
 112 testfunc(param) {
 113   // Do something ...
 114   // over a couple of lines.
 115 }
 116 @endcode
 117
 118 You can pass by reference.  That is, the parameter you pass is changed
 119 outside of the function.  For example:
 120
 121 @code
 122 testfunc(&param) {
 123   param = 10
 124   // The passed variable will be set to 10 outside of the function.
 125 }
 126 @endcode
 127
 128 To pass an array:
 129
 130 @code
 131 testfunc(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
 140 Small has the following control structures, which similar to their C
 141 counterparts:
 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
 158 The 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
 174 Embryo provides a minimal set of native calls that can be used within
 175 any 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
 186 Returns the number of arguments passed to a function.  Useful
 187 when dealing with variable argument lists.
 188
 189 @subsection Getargs_Desc getarg(arg, index=0)
 190
 191 Retrieves the argument number @c arg.  If the argument is an array,
 192 use @c index to specify the index of the array to return.
 193
 194 @subsection Setargs_Desc setargs(arg, index=0, value)
 195
 196 Sets the argument number @c arg to the given @c arg.  @c index specifies
 197 the index of @c arg to set if @c arg is an array.
 198
 199 @section String_ANC_Section String Functions
 200
 201 Functions that work on strings.
 202
 203 @subsection Atoi_Desc atoi
 204
 205 Translates an number in string form into an integer.
 206
 207 @subsection Fnmatch_Desc fnmatch
 208
 209 Buggered if I know what this does?
 210
 211 @subsection Strcmp_Desc strcmp
 212
 213 String 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
 250 Returns 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
 263 Returns a random integer.
 264
 265 @subsection Randf_Desc randf()
 266
 267 Returns a random float.
 268
 269 @file Embryo.h
 270 @brief Embryo virtual machine library.
 271
 272 This file includes the routines needed for Embryo library interaction.
 273 This 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
 340 extern "C" {
 341 #endif
 342
 343 #define EMBRYO_VERSION_MAJOR 1
 344 #define EMBRYO_VERSION_MINOR 6
 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  */
 440 EAPI 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  */
 448 EAPI 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  */
 463 EAPI 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  */
 473 EAPI 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  */
 482 EAPI 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  */
 489 EAPI 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  */
 504 EAPI 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  */
 530 EAPI 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  */
 540 EAPI 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  */
 552 EAPI 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  */
 569 EAPI 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  */
 577 EAPI 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  */
 586 EAPI 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  */
 605 EAPI 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  */
 613 EAPI 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  */
 624 EAPI 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  */
 638 EAPI 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  */
 646 EAPI 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  */
 661 EAPI 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  */
 668 EAPI 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  */
 677 EAPI 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  */
 692 EAPI 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  */
 701 EAPI 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  */
 711 EAPI 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  */
 721 EAPI 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  */
 740 EAPI 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  */
 749 EAPI 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  */
 764 EAPI 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   func 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  */
 784 EAPI 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  */
 794 EAPI 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  */
 844 EAPI 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  */
 858 EAPI 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  */
 874 EAPI 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  */
 884 EAPI 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  */
 895 EAPI int              embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num);
 896
 897 #ifdef  __cplusplus
 898 }
 899 #endif
 900
 901 #endif