Embryo_Run_Group(3)

NAME
Embryo_Run_Group - Program Run Functions

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

SYNOPSIS

  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

  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.

  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.

  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.

  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.

  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.

Author

Generated automatically by Doxygen for EFL from the source code.