@ciao-lang/ts-ciao-interface

Version:

Simple Ciao interface for node.

42 lines • 13 kB

HTML

<!DOCTYPE HTML><html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Multiple argument indexing — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="ExtendLang.html">↑</a><a class="lpdoc-navbutton" href="mutables.html">←</a><a class="lpdoc-navbutton" href="block_doc.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a></span><span><a href="ciaofulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> »<br/> </li><li><a href="ExtendLang.html">PART IV - Language extensions</a> »<br/> </li><li><a href=""><strong>Multiple argument indexing</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Usage and interface">Usage and interface</a></li><li><a href="#Documentation on exports">Documentation on exports</a></li><li><a href="#Documentation on internals">Documentation on internals</a></li><li><a href="#Documentation on imports">Documentation on imports</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Multiple argument indexing</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#indexer"></a> <strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Anil Nair" href="ciaosearch.html#Anil Nair">Anil Nair (original work)</a>, <a class="lpdoc-idx-anchor" id="Tom Howland" href="ciaosearch.html#Tom Howland">Tom Howland (<a href="http://home.pacbell.net/tomjdnh/pd.html">http://home.pacbell.net/tomjdnh/pd.html</a>, derived the original work)</a>, <a class="lpdoc-idx-anchor" id="Francisco Bueno" href="ciaosearch.html#Francisco Bueno">Francisco Bueno (initial port to Ciao)</a>, <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="ciaosearch.html#Jose F. Morales">Jose F. Morales (improvements in implementation and documentation)</a>.<p> Indexing (in Prolog) is an optimization technique that reduces the search space of the predicates without altering the Prolog semantics.<p>In the most general case, predicate clauses are tryed on backtracking one after the other, in sequential order. We can call this list of clauses a <em>try-list</em>. Indexing is based on removing clauses that are known to fail without any observable output (no side-effects) from the try-list. A typical implementation introduces tests before the actual predicate execution to discriminate among a collection of precomputed specialized try-lists. In the best case, this technique can obtain try-lists with 0 or 1 elements for calls.<p>Currently, the Ciao engine implements a limited but fast 1st-argument-1st-level indexing. The <a class="lpdoc-idx-anchor" id="0" href=""><tt>indexer</tt></a> package provides more powerful indexing schemes. It lets you pick different combinations of arguments to index on. E.g., it will let you index on the first and third argument or the second and the third argument of a predicate.<p>The selection of the try-list is based on computing a hash value for the terms (or part of them) to be indexed upon. Given this, the optimization pays off only when the amount of clashing that your original predicate causes without indexing superseeds the cost of the hashing function. Such amount of course depends on the number and form of the facts in your predicate, and the calling modes.<p><div class="lpdoc-alert"> <strong>Important Note about Performance</strong> <p><ul> <li>The current implementation of the package is done at the source level, so it may sometimes not be as fast as expected.<p><li>The complexity of the hashing function currently used is <script type="math/tex">O(n)</script> with <script type="math/tex">n</script> the number of characters in the textual representation of the term. Thus, even if the search tree is reduced, performance can be much slower in some cases that the cheaper internal (1st argument, 1st level) indexing used in Ciao. </ul> <p>Despite this, the package implements some indexing schemes with <strong>low overhead</strong>. <ul> <li>A single <a class="lpdoc-idx-anchor" id="1" href="ciaosearch.html#:- index p(+,?,...?)"><tt>:- index p(+,?,...?)</tt></a> indexer (1st argument, 1st level). Reuses the internal indexing.<p><li>A single <a class="lpdoc-idx-anchor" id="2" href="ciaosearch.html#:- index p(?,...,+,...?)"><tt>:- index p(?,...,+,...?)</tt></a> indexer (one argument, 1st level). Reuses the internal indexing by reordering the predicate arguments. </ul> </div> <br/><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/>This facility is used as a package, thus either including <a class="lpdoc-idx-anchor" id="3" href=""><tt>indexer</tt></a> in the package list of the module, or by using the <a class="lpdoc-idx-anchor" id="4" href="toplevel_doc.html#use_package/1"><tt>use_package/1</tt></a> declaration. The facility predicate <a class="lpdoc-idx-anchor" id="5" href="#hash_term/2"><tt>hash_term/2</tt></a>, documented here, is defined in library module <a class="lpdoc-idx-anchor" id="6" href="ciaosearch.html#library(indexer/hash)"><tt>library(indexer/hash)</tt></a>.<li><strong>Exports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Predicates:</em><br/><a class="lpdoc-idx-anchor" id="7" href="#hash_term/2"><tt>hash_term/2</tt></a>. </ul></ul></div></div><div id="Documentation on exports"><h2>Documentation on exports</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">PREDICATE</span><a class="lpdoc-idx-anchor" id="hash_term/2" href="ciaosearch.html#hash_term/2">hash_term/2</a></div><div class="lpdoc-deftext"><span class="lpdoc-usage-decl"><tt>hash_term(Term,HashValue)</tt> </span><p>Provides an efficient way to calculate an integer <span class="lpdoc-var">HashValue</span> for a ground <span class="lpdoc-var">Term</span>.<p><span class="lpdoc-usage-header">Usage 1:</span><span class="lpdoc-usage-decl"><tt>hash_term(T,N)</tt> </span><p><span class="lpdoc-var">N</span> is a hashing index for <span class="lpdoc-var">T</span>.</p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="8" href="term_typing.html#ground/1"><tt>term_typing:ground/1</tt></a>)</span><span><span class="lpdoc-var">T</span> is currently ground (it contains no variables). </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="9" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)</span><span><span class="lpdoc-var">N</span> is a free variable. </span> <li><em>The following properties should hold upon exit:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="10" href="basic_props.html#int/1"><tt>basic_props:int/1</tt></a>)</span><span><span class="lpdoc-var">N</span> is an integer. </span> </ul><p><span class="lpdoc-usage-header">Usage 2:</span><span class="lpdoc-usage-decl"><tt>hash_term(T,N)</tt> </span><p></p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold at call time:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="11" href="native_props_shfrg_doc.html#nonground/1"><tt>native_props:nonground/1</tt></a>)</span><span><tt><span class="lpdoc-var">T</span></tt> is not ground. </span><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="12" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)</span><span><span class="lpdoc-var">N</span> is a free variable. </span> <li><em>The following properties should hold upon exit:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="13" href="term_typing.html#var/1"><tt>term_typing:var/1</tt></a>)</span><span><span class="lpdoc-var">N</span> is a free variable. </span> </ul></div></div><p> </div><div id="Documentation on internals"><h2>Documentation on internals</h2><div><div class="lpdoc-defname"><span class="lpdoc-predtag">DECLARATION</span><a class="lpdoc-idx-anchor" id="index/1" href="ciaosearch.html#index/1">index/1</a></div><div class="lpdoc-deftext"><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl">:- <tt>index(IndexSpecs)</tt>. </span><p>Declares an indexing scheme for a predicate. Each spec declares an indexing on a combination of the arguments. Indexing will be performed using any of the specs in <span class="lpdoc-var">IndexSpecs</span> (being thus interpreted as an or).<p>You should use a <tt>*</tt> in an argument position if you wish to hash on the entire term in that argument. If a <tt>+</tt> is used only one level of the term in the argument is used for hashing. An <tt>i</tt> is used to indicate that argument is already an integer, and therefore its own value will be used for hashing. The argspec <tt>?</tt> simply indicates not to use the argument for indexing.<p>For example, the index specification: <pre class="lpdoc-codeblock">:- index foo(+,?,*,i), foo(?,?,?,i). </pre> declares indexing for <tt>foo/4</tt> either on a combination of the first, third, and fourht arguments, or only on the last argument, which is an integer. In the first case, only the principal functor of the first argument will be used for hashing; the third argument will be used in its entirety.<p>The argspec <tt>n</tt> is a pragmatic extension and can not be used in conjunction with the other specifiers aside from <tt>?</tt>. It stands for "nonvar" and implies that the argument will not be used for hashing, since only ground terms can effectively be used in hashing. Thus, it can not be used in combination with other specifiers within a particular index specification. It is often the fastest thing to use. </p><ul class="lpdoc-itemize-minus"><li><em>The following properties should hold upon exit:</em><br/><span class="lpdoc-on-right"> (<a class="lpdoc-idx-anchor" id="14" href="#indexspecs/1"><tt>indexer_doc:indexspecs/1</tt></a>)</span><span><span class="lpdoc-var">IndexSpecs</span> is an index specification. </span> </ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="indexspecs/1" href="ciaosearch.html#indexspecs/1">indexspecs/1</a></div><div class="lpdoc-deftext">An index specification is defined as follows: <pre class="lpdoc-codeblock">indexspecs(Spec) :- indexspec(Spec). indexspecs((Spec,Specs)) :- indexspec(Spec), indexspecs(Specs). </pre> <pre class="lpdoc-codeblock">indexspec(Spec) :- Spec=..[_F|Args], list(argspec,Args). </pre><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>indexspecs(IndexSpecs)</tt> </span><p><span class="lpdoc-var">IndexSpecs</span> is an index specification.</p><ul class="lpdoc-itemize-minus"></ul></div></div><p> <div><div class="lpdoc-defname"><span class="lpdoc-predtag">REGTYPE</span><a class="lpdoc-idx-anchor" id="argspec/1" href="ciaosearch.html#argspec/1">argspec/1</a></div><div class="lpdoc-deftext">An argument hash specification is defined as follows: <pre class="lpdoc-codeblock">argspec(+). argspec(*). argspec(i). argspec(n). argspec(?). </pre><p><span class="lpdoc-usage-header">Usage:</span><span class="lpdoc-usage-decl"><tt>argspec(Spec)</tt> </span><p><span class="lpdoc-var">Spec</span> is an argument hash specification.</p><ul class="lpdoc-itemize-minus"></ul></div></div><p> </div><div id="Documentation on imports"><h2>Documentation on imports</h2>This module has the following direct dependencies:<ul class="lpdoc-itemize-minus"><li><em>System library modules:</em><br/><a class="lpdoc-idx-anchor" id="15" href="ciaosearch.html#native_props"><tt>native_props</tt></a>, <a class="lpdoc-idx-anchor" id="16" href="ciaosearch.html#hash"><tt>hash</tt></a>. <li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="17" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="18" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="19" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="20" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="21" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>, <a class="lpdoc-idx-anchor" id="22" href="regtypes_doc.html"><tt>regtypes</tt></a>. </ul></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>