Program Run Functions
Embryo

Functions that are involved in actually running functions in an Embryo program. More...

## Functions

EAPI int | embryo_program_recursion_get (Embryo_Program *ep)
| Returns the number of virtual machines are running for the given program.
EAPI Embryo_Status | embryo_program_run (Embryo_Program *ep, Embryo_Function func)
| Runs the given function of the given Embryo program in the current virtual machine.
EAPI Embryo_Cell | embryo_program_return_value_get (Embryo_Program *ep)
| Retreives the return value of the last called function of the given program.
EAPI void | embryo_program_max_cycle_run_set (Embryo_Program *ep, int max)
| Sets the maximum number of abstract machine cycles any given program run can execute before being put to sleep and returning.
EAPI int | embryo_program_max_cycle_run_get (Embryo_Program *ep)
| Retreives the maximum number of abstract machine cycles a program is allowed to run.

## Detailed Description

Functions that are involved in actually running functions in an Embryo program.

## Function Documentation

## embryo_program_recursion_get()

EAPI int embryo_program_recursion_get | ( | Embryo_Program * | ep | ) |

Returns the number of virtual machines are running for the given program.

Parameters

  ep | The given program.

Returns
  The number of virtual machines running.

## embryo_program_run()

EAPI Embryo_Status embryo_program_run | ( | Embryo_Program * | ep,
|  | Embryo_Function | func )

Runs the given function of the given Embryo program in the current virtual machine.

The parameter `fn` can be found using embryo_program_function_find.

Note
  For Embryo to be able to run a function, it must have been declared `public` in the Small source code.

Parameters

  ep | The given program.
  func | The given function. Normally "main", in which case the constant `EMBRYO_FUNCTION_MAIN` can be used.

Returns
  `EMBRYO_PROGRAM_OK` on success. `EMBRYO_PROGRAM_SLEEP` if the program is halted by the Small `sleep` call. `EMBRYO_PROGRAM_FAIL` if there is an error. `EMBRYO_PROGRAM_TOOLONG` if the program executes for longer than it is allowed to in abstract machine instruction count.

References EMBRYO_CELL_NONE, embryo_data_address_get(), embryo_data_heap_push(), embryo_data_string_set(), EMBRYO_ERROR_BOUNDS, EMBRYO_ERROR_DIVIDE, EMBRYO_ERROR_HEAPLOW, EMBRYO_ERROR_INDEX, EMBRYO_ERROR_INIT, EMBRYO_ERROR_INVINSTR, EMBRYO_ERROR_MEMACCESS, EMBRYO_ERROR_SLEEP, EMBRYO_FUNCTION_CONT, and EMBRYO_FUNCTION_MAIN.

## embryo_program_return_value_get()

EAPI Embryo_Cell embryo_program_return_value_get | ( | Embryo_Program * | ep | ) |

Retreives the return value of the last called function of the given program.

Parameters

  ep | The given program.

Returns
  An Embryo_Cell representing the return value of the function that was last called.

## embryo_program_max_cycle_run_set()

EAPI void embryo_program_max_cycle_run_set | ( | Embryo_Program * | ep,
|  | int | max )

Sets the maximum number of abstract machine cycles any given program run can execute before being put to sleep and returning.

Parameters

  ep | The given program.
  max | The number of machine cycles as a limit.

This sets the maximum number of abstract machine (virtual machine) instructions that a single run of an embryo function (even if its main) can use before embryo embryo_program_run() reutrns with the value EMBRYO_PROGRAM_TOOLONG. If the function fully executes within this number of cycles, embryo_program_run() will return as normal with either EMBRYO_PROGRAM_OK, EMBRYO_PROGRAM_FAIL or EMBRYO_PROGRAM_SLEEP. If the run exceeds this instruction count, then EMBRYO_PROGRAM_TOOLONG will be returned indicating the program exceeded its run count. If the app wishes to continue running this anyway - it is free to process its own events or whatever it wants and continue the function by calling embryo_program_run(program, EMBRYO_FUNCTION_CONT); which will start the run again until the instruction count is reached. This can keep being done to allow the calling program to still be able to control things outside the embryo function being called. If the maximum run cycle count is 0 then the program is allowed to run forever only returning when it is done.

It is important to note that abstract machine cycles are NOT the same as the host machine cpu cycles. They are not fixed in runtime per cycle, so this is more of a helper tool than a way to HARD-FORCE a script to only run for a specific period of time. If the cycle count is set to something low like 5000 or 1000, then every 1000 (or 5000) cycles control will be returned to the calling process where it can check a timer to see if a physical runtime limit has been elapsed and then abort running further assuming a "runaway script" or keep continuing the script run. This limits resolution to only that many cycles which do not take a determined amount of time to execute, as this varies from cpu to cpu and also depends on how loaded the system is. Making the max cycle run too low will impact performance requiring the abstract machine to do setup and teardown cycles too often comapred to cycles actually executed.

Also note it does NOT include nested abstract machines. IF this abstract machine run calls embryo script that calls a native function that in turn calls more embryo script, then the 2nd (and so on) levels are not included in this run count. They can set their own max instruction count values separately.

The default max cycle run value is 0 in any program until set with this function.

## embryo_program_max_cycle_run_get()

EAPI int embryo_program_max_cycle_run_get | ( | Embryo_Program * | ep | ) |

Retreives the maximum number of abstract machine cycles a program is allowed to run.

Parameters

  ep | The given program.

Returns
  The number of cycles a run cycle is allowed to run for this program.

This returns the value set by embryo_program_max_cycle_run_set(). See embryo_program_max_cycle_run_set() for more information.