Previous Up Next

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.

Previous Up Next