 
 
 
C.8  Passing Control and Data to ECLiPSe from C
These are the functions needed to embed ECLiPSe into C code.
- 
void		ec_post_goal(const pword)
-  
 post a goal (constraint) that will be executed when ECLiPSe	is resumed.
- void		ec_post_string(const char *)
-  
 same as ec_post_goal(), but the goal is given in ECLiPSe syntax
	in a string. This should only be used if speed is not critical
	and if the goal does not contain variables whose values may be
	needed later.
	This function is part of the simplified interface.
- void		ec_post_exdr(int len, const char *exdr)
-  
 same as ec_post_goal(), but the goal is given in EXDR format
	(see chapter 9).
	This function is part of the simplified interface.
- int		ec_resume()
-  
 resume execution of the ECLiPSe engine: All posted goals will
	be executed and all posted events will be handled.
	The return value will be PSUCCEED if the goals succeed
	PFAIL is returned if the goals fail, and PYIELD if control was
	yielded because of a
	yield/2
	predicate call in the ECLiPSe code.
	If a writable queue stream with yield-option
	(see open/4)
	was flushed, the return value is PFLUSHIO.
	If there was an attempt to read from an empty queue stream with
	yield-option, the return value is PWAITIO.
	If an asynchronous ECLiPSe thread is already running,
	PRUNNING is returned.
	No parameters can be passed.
	This function is part of the simplified interface.
- int		ec_resume1(ec_ref ToC)
-  
 Similar to ec_resume(), but if the return value is PSUCCED,
	the ToC argument returns a cut value that can be used to discard
	alternative solutions by passing it to ec_cut_to_chp().
	If the return value is PYIELD, control was yielded because of a
	yield/2
	predicate call in the ECLiPSe code, and ToC contains the data
	passed by the first argument of
	yield/2.
	If the return value is PFLUSHIO or PWAITIO, ToC contains
	the associated stream number.
- int		ec_resume2(const pword FromC,ec_ref ToC)
-  
 Similar to ec_resume1(), but it allows to pass an argument
	to the resumed execution. This is only useful if the execution
	had yielded due to a
	yield/2
	predicate call. The term FromC is passed as input into the
	second argument of
	yield/2.
- int		ec_resume_long(long *ToC)
-  
 Similar to ec_resume1(), but allows only integer values to be passed
	from ECLiPSe to C (otherwise TYPE_ERROR is returned).
	This function is part of the simplified interface.
- int		ec_resume_async()
-  
 Similar to ec_resume(), but ECLiPSe is resumed in a separate
	thread in case this is supported by the operating system.
	The return value is PSUCCED if the thread started successfully,
	SYS_ERROR if there was a problem creating the thread, and
	PRUNNING if there was already an ECLiPSe thread running
	(only one ECLiPSe thread is allowed to run at any time).
	If threads are not supported, the call does nothing and return
	PSUCCED. Use ec_resume_status() to wait for termination and
	to retrieve the results of the execution.
- int		ec_resume_status()
-  
 This function is supposed to be called after a call to
	ec_resume_async(). It returns PRUNNING as long as the ECLiPSe
	thread is still running. If the thread has stopped, the return
	values are the same as for ec_resume().
	If threads are not supported, the pair of ec_resume_async()
	and ec_resume_status() is equivalent to an ec_resume().
- int		ec_resume_status_long(long *ToC)
-  
 Similar to ec_resume_status(), but allows an integer to be
	returned to the caller, as done by ec_resume_long().
- int		ec_wait_resume_status_long(long *ToC, int timeout)
-  
 Similar to ec_resume_status_long(), but waits for the ECLiPSe thread
	to finish execution. The function returns as soon as the ECLiPSe thread
	is finished, or after timeout milliseconds, whatever is earlier.
	In case of timeout, the return value will be PRUNNING. If timeout is
	zero, the function is equivalent to ec_resume_status_long().
	If timeout is negative, there will be no timeout and the function
	will only return when the ECLiPSe thread is finished.
- int		ec_handle_events(long *ToC)
-  
 Similar to ec_resume_long(), but posted goals are not executed,
	only events are handled.
- void		ec_cut_to_chp(ec_ref)
-  
 Cut all choicepoints created by the batch of goals whose execution
	succeeded. The argument should have been obtained by a call to
	ec_resume2().
- int		ec_post_event(pword Name)
-  
 Post an event to the ECLiPSe engine. This will lead to the
	execution of the corresponding event handler once the ECLiPSe	execution is resumed. See also event/1 and the User Manual
	chapter on event handling for more information.
	Name should be an ECLiPSe atom.
- int		ec_post_event_string(const char *)
-  
 Post an event to the ECLiPSe engine. This will lead to the
	execution of the corresponding event handler once the ECLiPSe	execution is resumed. See also event/1 and the User Manual
	chapter on event handling for more information. The event name
	is given as a string.
	This function is part of the simplified interface.
 
 
