C.8  Passing Control and Data to ECLⁱPS^e from C

These are the functions needed to embed ECLⁱPS^e into C code.

void ec_post_goal(const pword)

post a goal (constraint) that will be executed when ECLⁱPS^e is resumed.

void ec_post_string(const char *)

same as ec_post_goal(), but the goal is given in ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e to C (otherwise TYPE_ERROR is returned). This function is part of the simplified interface.

int ec_resume_async()

Similar to ec_resume(), but ECLⁱPS^e 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 ECLⁱPS^e thread running (only one ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e thread to finish execution. The function returns as soon as the ECLⁱPS^e 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 ECLⁱPS^e 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 ECLⁱPS^e engine. This will lead to the execution of the corresponding event handler once the ECLⁱPS^e execution is resumed. See also event/1 and the User Manual chapter on event handling for more information. Name should be an ECLⁱPS^e atom.

int ec_post_event_string(const char *)

Post an event to the ECLⁱPS^e engine. This will lead to the execution of the corresponding event handler once the ECLⁱPS^e 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.