[Bigdata-commit] SF.net SVN: bigdata:[8005] branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/ java/com/bigdata/rdf/sparql/ast/eval/ASTEvalHelper.java

[<tho...@us...>]

Revision: 8005
          http://sourceforge.net/p/bigdata/code/8005
Author:   thompsonbry
Date:     2014-03-22 11:06:14 +0000 (Sat, 22 Mar 2014)
Log Message:
-----------
javadoc on the semantics of interrupting (a) the submission of a query; and (b) a running query.

See #864 and #707.

Modified Paths:
--------------
    branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/eval/ASTEvalHelper.java

Modified: branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/eval/ASTEvalHelper.java
===================================================================
--- branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/eval/ASTEvalHelper.java	2014-03-21 01:21:03 UTC (rev 8004)
+++ branches/BIGDATA_RELEASE_1_3_0/bigdata-rdf/src/java/com/bigdata/rdf/sparql/ast/eval/ASTEvalHelper.java	2014-03-22 11:06:14 UTC (rev 8005)
@@ -63,6 +63,7 @@
 import com.bigdata.bop.PipelineOp;
 import com.bigdata.bop.bindingSet.ListBindingSet;
 import com.bigdata.bop.engine.IRunningQuery;
+import com.bigdata.bop.engine.QueryEngine;
 import com.bigdata.bop.rdf.join.ChunkedMaterializationIterator;
 import com.bigdata.journal.TimestampUtility;
 import com.bigdata.rdf.internal.IV;
@@ -659,6 +660,38 @@
 
     /**
      * Evaluate a query plan (core method).
+     * <p>
+     * As explained in some depth at <a
+     * href="https://sourceforge.net/apps/trac/bigdata/ticket/707">
+     * BlockingBuffer.close() does not unblock threads </a> and <a
+     * href="http://trac.bigdata.com/ticket/864"> Semantics of interrupting a
+     * running query</a>, (a) you can not interrupted the thread that submits a
+     * query until the {@link CloseableIteration} has been returned to the
+     * caller submitting that query; (b)
+     * <p>
+     * (a) If you interrupt the thread submitting the query, the query may
+     * actually execute. This can occur because the interrupt can arise between
+     * the time at which the query begins to execute on the {@link QueryEngine}
+     * and the time at which the {@link IRunningQuery} object is bound up inside
+     * of the returned {@link CloseableIteration} and returned to the caller.
+     * Until the caller has possession of the {@link CloseableIteration}, an
+     * interrupt will not cause the associated {@link IRunningQuery} to be
+     * terminated. See <a
+     * href="https://sourceforge.net/apps/trac/bigdata/ticket/707">
+     * BlockingBuffer.close() does not unblock threads </a>
+     * <p>
+     * (b) If you interrupt the thread draining the solutions from the
+     * {@link CloseableIteration} or otherwise cause
+     * {@link CloseableIteration#close()} to become invoked, then the
+     * {@link IRunningQuery} will be interrupted. Per <a
+     * href="http://trac.bigdata.com/ticket/864"> Semantics of interrupting a
+     * running query</a>, that interrupt is interpreted as <em>normal</em>
+     * termination (this supports the use case of LIMIT and is built deeply into
+     * the {@link QueryEngine} semantics). In order for the application to
+     * distinguish between a case where it has interrupted the query and a case
+     * where the query has been interrupted by a LIMIT, the application MUST
+     * notice when it decides to interrupt a given query and then discard the
+     * outcome of that query.
      * 
      * @param astContainer
      *            The query model.
@@ -682,6 +715,11 @@
      *         containing the solutions for the query.
      * 
      * @throws QueryEvaluationException
+     * 
+     * @see <a href="https://sourceforge.net/apps/trac/bigdata/ticket/707">
+     *      BlockingBuffer.close() does not unblock threads </a>
+     * @see <a href="http://trac.bigdata.com/ticket/864"> Semantics of
+     *      interrupting a running query</a>
      */
     static //private Note: Exposed to CBD class.
     CloseableIteration<BindingSet, QueryEvaluationException> evaluateQuery(

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.