1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22% 23% $Id: embsumc.tex,v 1.3 2015/01/14 01:31:09 jschimpf Exp $ 24% 25 26\chapter{Summary of C Interface Functions} 27%HEVEA\cutdef[1]{section} 28\label{chapsumc} 29Note that a self-contained subset of the functions described here 30uses only integer and string arguments and is therefore suitable 31to be used in situations where no complex types can be passed, 32e.g.\ when interfacing to scripting languages. 33 34\section{Constructing {\eclipse} terms in C} 35All these functions return (volatile) pwords, which can be used as input 36to other constructor functions, or which can be stored in (non-volatile) 37ec_refs. 38 39\begin{description} 40\item[pword ec_string(const char*)]\ \\ 41 converts a C string to an {\eclipse} string. The string is copied. 42 43\item[pword ec_length_string(int, const char*)]\ \\ 44 converts a C string of given length to an {\eclipse} string. 45 The string is copied and can contain NUL bytes. 46 47\item[pword ec_atom(const dident)]\ \\ 48 creates an {\eclipse} atom. A dident (dictionary identifier) 49 can be obtained either via ec_did() or ec_get_atom(). 50 51\item[pword ec_long(const long)]\ \\ 52 converts a C long to an {\eclipse} integer. 53 54\item[pword ec_long_long(const long long)]\ \\ 55 converts a C long long to an {\eclipse} integer. 56 57\item[pword ec_double(const double)]\ \\ 58 converts a C double to an {\eclipse} float. 59 60\item[pword ec_term(dident,pword,pword,...)]\ \\ 61 creates an {\eclipse} term from the given components. 62 63\item[pword ec_term_array(const dident,const pword\nil)]\ \\ 64 creates an {\eclipse} term from the arguments given in the array. 65 66\item[pword ec_list(const pword,const pword)]\ \\ 67 creates a single {\eclipse} list cell with the given head (car) and tail (cdr). 68 69\item[pword ec_listofrefs(ec_refs)]\ \\ 70 creates an {\eclipse} list containing the elements of the ec_refs array. 71 72\item[pword ec_listoflong(int, const long*)]\ \\ 73 creates an {\eclipse} list of integers containing the longs in the given array. 74 The data is copied. 75 76\item[pword ec_listofchar(int, const char*)]\ \\ 77 creates an {\eclipse} list of integers containing the chars in the given array. 78 The data is copied. 79 80\item[pword ec_listofdouble(int, const double*)]\ \\ 81 creates an {\eclipse} list of doubles containing the doubles in the given array. 82 The data is copied. 83 84\item[pword ec_arrayofdouble(int, const double*)]\ \\ 85 creates an {\eclipse} array (a structure with functor \nil of 86 appropriate arity) of doubles from the given C array. 87 The data is copied. 88 89\item[pword ec_matrixofdouble(int rows, int cols, const double*)]\ \\ 90 creates an {\eclipse} array (size rows) of arrays (size cols) of doubles 91 from the given C array. The data is copied. 92 93\item[pword ec_handle(const t_ext_type*,const t_ext_ptr)]\ \\ 94 creates an {\eclipse} handle that refers to the given C data and its 95 method table. 96 97\item[pword ec_newvar()]\ \\ 98 creates a fresh {\eclipse} variable. 99 100\item[pword ec_nil()]\ \\ 101 creates an {\eclipse} nil ie.\ the empty list \nil. 102\end{description} 103 104Auxiliary functions to access the {\eclipse} dictionary. 105\begin{description} 106\item[dident ec_did(char*,int)]\ \\ 107 looks up or enters the given string with arity into the {\eclipse} 108 dictionary and returns a unique identifier for it. 109\item[char* DidName(dident)]\ \\ 110 returns the name string of the given dictionary identifier. 111\item[int DidArity(dident)]\ \\ 112 returns the arity of the given dictionary identifier. 113\end{description} 114 115 116 117\section{Decomposing {\eclipse} terms in C} 118The following group of functions type-check an {\eclipse} term and 119retrieve its contents if it is of the correct type. 120The return code is PSUCCEED for successful conversion. 121If a variable was encountered instead INSTANTIATION_FAULT is returned. 122Other unexpected types yield a TYPE_ERROR. Special cases are explained below. 123\begin{description} 124 125\item[int ec_get_string(const pword,char**)]\ \\ 126 checks whether the {\eclipse} pword is a string (or atom) and converts 127 it to a C string. This string is volatile, ie.\ it should be copied 128 when it is required to survive resuming of {\eclipse}. 129 130\item[int ec_get_string_length(const pword,char**,long*)]\ \\ 131 the same as ec_get_string(), but returns also the string's length. 132 Note that {\eclipse} strings may contain null characters! 133 134\item[int ec_get_atom(const pword,dident*)]\ \\ 135 checks whether the {\eclipse} pword is an atom, and if so, 136 return its dictionary identifier. 137 138\item[int ec_get_long(const pword,long*)]\ \\ 139 checks whether the {\eclipse} pword is an integer that fits into 140 a C long, and if so, stores it via the pointer provided. 141 Otherwise, the return code is RANGE_ERROR. 142 143\item[int ec_get_long_long(const pword,long long*)]\ \\ 144 checks whether the {\eclipse} pword is an integer that fits into 145 a C long long, and if so, stores it via the pointer provided. 146 Otherwise, the return code is RANGE_ERROR. 147 148\item[int ec_get_double(const pword,double*)]\ \\ 149 checks whether the {\eclipse} pword is a floating point number, 150 and if so, returns it as an C double. 151 152\item[int ec_get_nil(const pword)]\ \\ 153 checks whether the {\eclipse} pword is nil, the empty list. 154 155\item[int ec_get_list(const pword,pword*,pword*)]\ \\ 156 checks whether the {\eclipse} pword is a list, and if so, 157 returns its head and tail. If it is nil, the return code is PFAIL. 158 159\item[int ec_get_functor(pword,dident*)]\ \\ 160 checks whether the {\eclipse} pword is a structure, and if so, 161 returns the functor. 162 163\item[int ec_get_arg(const int n,pword,pword*)]\ \\ 164 checks whether the {\eclipse} pword is a structure, and if so, 165 returns the n'th argument. The return code is RANGE_ERROR 166 if the argument index is out of range. 167 168\item[int ec_arity(pword)]\ \\ 169 returns the arity (number of arguments) of an {\eclipse} pword 170 if it is a structure, otherwise zero. 171 172\item[int ec_get_handle(const pword,const t_ext_type*,t_ext_ptr*)]\ \\ 173 checks whether the {\eclipse} pword is a handle whose method table 174 matches the given one, and if so, the data pointer is returned. 175 176\item[int ec_is_var(const pword)]\ \\ 177 checks whether the {\eclipse} pword is a variable. 178 Note that the return values are PSUCCEED are PFAIL 179 rather than standard C truth values. 180 181\end{description} 182 183 184\section{Referring to {\eclipse} terms from C} 185The data types ec_refs and ec_ref provide a means to have non-volatile 186references to {\eclipse} data from within C data structures. However, 187it must be kept in mind that {\eclipse} data structures are nevertheless 188subject to backtracking, which means they may be reset to an earlier 189status when the search engine requires it. Creating a reference to 190a data structure does not change that in any way. In particular, 191when the search engine fails beyond the state where the reference was 192set up, the reference disappears and is also reset to its earlier value. 193\begin{description} 194\item[ec_refs ec_refs_create(int n,const pword pw)]\ \\ 195 create a data structure capable of holding n non-volatile 196 references to {\eclipse} data items. They are initialised 197 with the value pw, which must be of a simple type. 198 199\item[ec_refs ec_refs_create_newvars(int)]\ \\ 200 like ec_refs_create(), but each item is initialised to 201 a freshly created {\eclipse} variable. 202 203\item[void ec_refs_destroy(ec_refs)]\ \\ 204 destroy the {\eclipse} references. It is important that this 205 is done, otherwise the {\eclipse} garbage collector will not 206 be able to free the references data structures, which may 207 eventually lead to memory overflow. 208 209\item[void ec_refs_set(ec_refs,int i,const pword pw)]\ \\ 210 set the i'th reference to the {\eclipse} term pw. This setting is 211 subject to the {\eclipse} engine's undo-mechanism on backtracking. 212 213\item[pword ec_refs_get(const ec_refs,int i)]\ \\ 214 return the {\eclipse} term referred to by the i'th reference. 215 216\item[int ec_refs_size(const ec_refs)]\ \\ 217 return the capacity of the ec_refs data structure. 218 219\item[ec_ref ec_ref_create(pword)]\ \\ 220 like ec_refs_create() for a single reference. 221 222\item[ec_ref ec_ref_create_newvar()]\ \\ 223 analogous to ec_refs_create_newvars(). 224 225\item[void ec_ref_destroy(ec_ref)]\ \\ 226 analogous to ec_refs_destroy(). 227 228\item[void ec_ref_set(ec_ref,const pword)]\ \\ 229 analogous to ec_refs_set(). 230 231\item[pword ec_ref_get(const ec_ref)]\ \\ 232 analogous to ec_refs_get(). 233\end{description} 234 235 236\section{Passing Data to and from External Predicates in C} 237These two functions are only meaningful inside C functions that have been 238called from {\eclipse} as external predicates. 239\begin{description} 240\item[pword ec_arg(int i)]\ \\ 241 If inside a C function called from {\eclipse}, this returns the 242 i'th argument of the call. 243 244\item[int ec_unify(pword,pword)]\ \\ 245 Unify the two given pwords. Note that, if attributed variables 246 are involved in the unification, the associated unification handlers 247 as well as subsequent waking will only happen once control is 248 returned to {\eclipse}. 249\end{description} 250 251 252\section{Operations on {\eclipse} Data} 253Interfaces to some basic operations on {\eclipse} Data. 254\begin{description} 255\item[int ec_compare(const pword pw1, const pword pw2)]\ \\ 256 Similar to the compare/3 built-in predicate: 257 returns 0 if the arguments are identical, 258 a negative number if pw1 is smaller than pw2, 259 and a positive number if pw1 is greater than pw2 260 in the standard term ordering. 261 262\item[int ec_schedule_suspensions(pword,int)]\ \\ 263 Similar to the 264 \bipref{schedule_suspensions/2}{../bips/kernel/suspensions/schedule_suspensions-2.html} 265 built-in predicate. 266 Waking will only happen once control is returned to {\eclipse} 267 and the wake/0 predicate is invoked. 268 Return code is PSUCCEED or an error code. 269 270\item[int ec_free_handle(const pword, const t_ext_type*)]\ \\ 271 checks whether pw is an {\eclipse} external data handle of the 272 expected type, and calls its free-method. After doing that, the 273 handle is stale and cannot be used any longer. Calling this function 274 on an already stale handle silently succeeds. 275 Return code is PSUCCEED or an error code. 276 277\end{description} 278 279 280\section{Initialising and Shutting Down the {\eclipse} Subsystem} 281These are the functions needed to embed {\eclipse} into a C main program. 282\begin{description} 283\item[int ec_set_option_long(int, long)]\ \\ 284 Set the value of a numerical option (see appendix \ref{chapecoptions}). 285 The numerical value can be of type long. 286 287\item[int ec_set_option_ptr(int, char *)]\ \\ 288 Set the value of a string-valued option (see appendix \ref{chapecoptions}). 289 290\item[int ec_init()]\ \\ 291 Initialise the {\eclipse} engine. This is required before any other 292 functions of this interface (except option setting) can be used. 293 294\item[int ec_cleanup()]\ \\ 295 Shutdown the {\eclipse} engine. 296\end{description} 297 298 299\section{Creating External Predicates in C} 300This function serves the same purpose as the {\eclipse} built-in external/2: 301\begin{description} 302\item[int ec_external(dident pred, int(*fct)(), dident module)]\ \\ 303 Creates a predicate pred in the given module, whose C/C++ 304 implementation is the function fct (see chapter \ref{chapext} 305 for how to write such functions). The module must exist. 306 Return code is PSUCCEED or an error code. 307\end{description} 308 309 310\section{Passing Control and Data to {\eclipse} from C} 311These are the functions needed to embed {\eclipse} into C code. 312\begin{description} 313\item[void ec_post_goal(const pword)]\ \\ 314 post a goal (constraint) that will be executed when \eclipse 315 is resumed. 316 317\item[void ec_post_string(const char *)]\ \\ 318 same as ec_post_goal(), but the goal is given in {\eclipse} syntax 319 in a string. This should only be used if speed is not critical 320 and if the goal does not contain variables whose values may be 321 needed later. 322 This function is part of the simplified interface. 323 324\item[void ec_post_exdr(int len, const char *exdr)]\ \\ 325 same as ec_post_goal(), but the goal is given in EXDR format 326 (see chapter \ref{chapexdr}). 327 This function is part of the simplified interface. 328 329\item[int ec_resume()]\ \\ 330 resume execution of the {\eclipse} engine: All posted goals will 331 be executed and all posted events will be handled. 332 The return value will be PSUCCEED if the goals succeed 333 PFAIL is returned if the goals fail, and PYIELD if control was 334 yielded because of a 335 \bipref{yield/2}{../bips/kernel/externals/yield-2.html} 336 predicate call in the {\eclipse} code. 337 If a writable queue stream with yield-option 338 (see \bipref{open/4}{../bips/kernel/iostream/open-4.html}) 339 was flushed, the return value is PFLUSHIO. 340 If there was an attempt to read from an empty queue stream with 341 yield-option, the return value is PWAITIO. 342 If an asynchronous {\eclipse} thread is already running, 343 PRUNNING is returned. 344 No parameters can be passed. 345 This function is part of the simplified interface. 346 347\item[int ec_resume1(ec_ref ToC)]\ \\ 348 Similar to ec_resume(), but if the return value is PSUCCED, 349 the ToC argument returns a cut value that can be used to discard 350 alternative solutions by passing it to ec_cut_to_chp(). 351 If the return value is PYIELD, control was yielded because of a 352 \bipref{yield/2}{../bips/kernel/externals/yield-2.html} 353 predicate call in the {\eclipse} code, and ToC contains the data 354 passed by the first argument of 355 \bipref{yield/2}{../bips/kernel/externals/yield-2.html}. 356 If the return value is PFLUSHIO or PWAITIO, ToC contains 357 the associated stream number. 358 359\item[int ec_resume2(const pword FromC,ec_ref ToC)]\ \\ 360 Similar to ec_resume1(), but it allows to pass an argument 361 to the resumed execution. This is only useful if the execution 362 had yielded due to a 363 \bipref{yield/2}{../bips/kernel/externals/yield-2.html} 364 predicate call. The term FromC is passed as input into the 365 second argument of 366 \bipref{yield/2}{../bips/kernel/externals/yield-2.html}. 367 368\item[int ec_resume_long(long *ToC)]\ \\ 369 Similar to ec_resume1(), but allows only integer values to be passed 370 from {\eclipse} to C (otherwise TYPE_ERROR is returned). 371 This function is part of the simplified interface. 372 373\item[int ec_resume_async()]\ \\ 374 Similar to ec_resume(), but {\eclipse} is resumed in a separate 375 thread in case this is supported by the operating system. 376 The return value is PSUCCED if the thread started successfully, 377 SYS_ERROR if there was a problem creating the thread, and 378 PRUNNING if there was already an {\eclipse} thread running 379 (only one {\eclipse} thread is allowed to run at any time). 380 If threads are not supported, the call does nothing and return 381 PSUCCED. Use ec_resume_status() to wait for termination and 382 to retrieve the results of the execution. 383 384\item[int ec_resume_status()]\ \\ 385 This function is supposed to be called after a call to 386 ec_resume_async(). It returns PRUNNING as long as the {\eclipse} 387 thread is still running. If the thread has stopped, the return 388 values are the same as for ec_resume(). 389 If threads are not supported, the pair of ec_resume_async() 390 and ec_resume_status() is equivalent to an ec_resume(). 391 392\item[int ec_resume_status_long(long *ToC)]\ \\ 393 Similar to ec_resume_status(), but allows an integer to be 394 returned to the caller, as done by ec_resume_long(). 395 396\item[int ec_wait_resume_status_long(long *ToC, int timeout)]\ \\ 397 Similar to ec_resume_status_long(), but waits for the {\eclipse} thread 398 to finish execution. The function returns as soon as the {\eclipse} thread 399 is finished, or after timeout milliseconds, whatever is earlier. 400 In case of timeout, the return value will be PRUNNING. If timeout is 401 zero, the function is equivalent to ec_resume_status_long(). 402 If timeout is negative, there will be no timeout and the function 403 will only return when the {\eclipse} thread is finished. 404 405\item[int ec_handle_events(long *ToC)]\ \\ 406 Similar to ec_resume_long(), but posted goals are not executed, 407 only events are handled. 408 409\item[void ec_cut_to_chp(ec_ref)]\ \\ 410 Cut all choicepoints created by the batch of goals whose execution 411 succeeded. The argument should have been obtained by a call to 412 ec_resume2(). 413 414\item[int ec_post_event(pword Name)]\ \\ 415 Post an event to the {\eclipse} engine. This will lead to the 416 execution of the corresponding event handler once the \eclipse 417 execution is resumed. See also \bipref{event/1}{../bips/kernel/event/event-1.html} and the User Manual 418 chapter on event handling for more information. 419 Name should be an {\eclipse} atom. 420 421\item[int ec_post_event_string(const char *)]\ \\ 422 Post an event to the {\eclipse} engine. This will lead to the 423 execution of the corresponding event handler once the \eclipse 424 execution is resumed. See also \bipref{event/1}{../bips/kernel/event/event-1.html} and the User Manual 425 chapter on event handling for more information. The event name 426 is given as a string. 427 This function is part of the simplified interface. 428\end{description} 429 430 431\section{Communication via {\eclipse} Streams} 432These functions allow exchanging data with an embedded {\eclipse} via 433queue streams created by the {\eclipse} code. 434Queue streams can be created either by using 435\bipref{open/3}{../bips/kernel/iostream/open-3.html} and 436\bipref{open/4}{../bips/kernel/iostream/open-4.html} 437from within 438{\eclipse} code, or by initializing {\eclipse} with the MEMORY_IO option. 439In the latter case, the streams 0, 1 and 2 are queues corresponding 440to {\eclipse}'s input, output and error streams. 441\begin{description} 442\item[int ec_queue_write(int stream, char *data, int size)]\ \\ 443 Write string data into the specified {\eclipse} queue stream. 444 Data points to the data and size is the number of bytes to write. 445 The return value is 0 for success, or a negative error number. 446 447\item[int ec_queue_read(int stream, char *buf, int size)]\ \\ 448 Read string data into the specified {\eclipse} queue stream. 449 Buf points to a data buffer and size is the buffer size. 450 The return value is either a negative error code, or the number 451 of bytes read into buffer. 452 453\item[int ec_queue_avail(int stream)]\ \\ 454 Determines the number of bytes that are available and can be 455 read from the given queue stream. The return value is either 456 that number or a negative error code. 457 458\item[int ec_stream_nr(char *name)]\ \\ 459 Get the stream number of the named stream. If the return value 460 is negative then there is no open stream with the specified name. 461 This is the same operation that the {\eclipse} built-in 462 \bipref{get_stream/2}{../bips/kernel/iostream/get_stream-2.html} 463 performs). 464\end{description} 465 466 467\section{Miscellaneous} 468These two functions provide an alternative method for posting goals and 469retrieving results. They are intended for applications with a simple structure 470that require only infrequent call-return style control transfers 471and little information passing between {\eclipse} and C. It is less powerful 472and less efficient that the primitives described above. 473\begin{description} 474\item[int ec_exec_string(char*,ec_ref Vars)]\ \\ 475 let {\eclipse} execute a goal given in a string {\eclipse} syntax. 476 Return value is PSUCCEED or PFAIL, depending on the result of 477 the execution. If successful, Vars holds a list mapping the 478 variables names within the string to their values after execution. 479 480\item[int ec_var_lookup(ec_ref Vars,char*,pword* pw)]\ \\ 481 Lookup the value of the variable with the given name. 482 Vars is a list as returned by ec_exec_string(). 483\end{description} 484 485%HEVEA\cutend 486