Mailing-List: contact commits-help@manifoldcf.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@manifoldcf.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1550411 - in
 /manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core:
 interfaces/ throttler/
Date: Thu, 12 Dec 2013 13:00:50 -0000
To: commits@manifoldcf.apache.org
From: kwright@apache.org
Message-Id: <20131212130050.91C292388C93@eris.apache.org>

Author: kwright
Date: Thu Dec 12 13:00:49 2013
New Revision: 1550411

URL: http://svn.apache.org/r1550411
Log:
Add hierarchical interfaces for throttling at different levels

Added:
    manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java   (with props)
    manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java   (with props)
Modified:
    manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IConnectionThrottler.java
    manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/ConnectionThrottler.java
    manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/Throttler.java

Modified: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IConnectionThrottler.java
URL: http://svn.apache.org/viewvc/manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IConnectionThrottler.java?rev=1550411&r1=1550410&r2=1550411&view=diff
==============================================================================
--- manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IConnectionThrottler.java (original)
+++ manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IConnectionThrottler.java Thu Dec 12 13:00:49 2013
@@ -33,70 +33,19 @@ public interface IConnectionThrottler
   *@param throttleSpec is the throttle specification to use for the throttle group,
   *@param binNames is the set of bin names to throttle for, within the throttle group.
   *@param currentTime is the current time, in ms. since epoch.
+  *@return the fetch throttler to use when performing fetches from this connection.
   */
-  public void obtainConnectionPermission(String throttleGroup,
+  public IFetchThrottler obtainConnectionPermission(String throttleGroup,
     IThrottleSpec throttleSpec, String[] binNames, long currentTime)
     throws ManifoldCFException;
   
   /** Release permission to use a connection. This presumes that obtainConnectionPermission()
   * was called earlier in the same thread and was successful.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  public void releaseConnectionPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException;
-  
-  /** Get permission to fetch a document.  This grants permission to start
-  * fetching a single document.  When done (or aborting), call
-  * releaseFetchDocumentPermission() to note the completion of the document
-  * fetch activity.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
   *@param currentTime is the current time, in ms. since epoch.
   */
-  public void obtainFetchDocumentPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
+  public void releaseConnectionPermission(long currentTime)
     throws ManifoldCFException;
   
-  /** Release permission to fetch a document.  Call this only when you
-  * called obtainFetchDocumentPermission() successfully earlier in the same
-  * thread.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  public void releaseFetchDocumentPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException;
-  
-  /** Obtain permission to read a block of bytes.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  *@param byteCount is the number of bytes to get permissions to read.
-  */
-  public void obtainReadPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime, int byteCount)
-    throws ManifoldCFException;
-    
-  /** Note the completion of the read of a block of bytes.  Call this after
-  * obtainReadPermission() was successfully called in the same thread.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  *@param origByteCount is the originally requested number of bytes to get permissions to read.
-  *@param actualByteCount is the number of bytes actually read.
-  */
-  public void releaseReadPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime, int origByteCount, int actualByteCount)
-    throws ManifoldCFException;
-
   /** Poll periodically.
   */
   public void poll()

Added: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java
URL: http://svn.apache.org/viewvc/manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java?rev=1550411&view=auto
==============================================================================
--- manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java (added)
+++ manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java Thu Dec 12 13:00:49 2013
@@ -0,0 +1,48 @@
+/* $Id$ */
+
+/**
+* Licensed to the Apache Software Foundation (ASF) under one or more
+* contributor license agreements. See the NOTICE file distributed with
+* this work for additional information regarding copyright ownership.
+* The ASF licenses this file to You under the Apache License, Version 2.0
+* (the "License"); you may not use this file except in compliance with
+* the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+package org.apache.manifoldcf.core.interfaces;
+
+/** An IFetchThrottler object is meant to be used as part of a fetch cycle.  It is not
+* thread-local, and does not require access to a thread context.  It thus also does not
+* throw ManifoldCFExceptions.  It is thus suitable for use in background threads, etc.
+* These objects are typically created by IConnectionThrottler objects - they are not meant
+* to be created directly.
+*/
+public interface IFetchThrottler
+{
+  public static final String _rcsid = "@(#)$Id$";
+
+  /** Get permission to fetch a document.  This grants permission to start
+  * fetching a single document, within the connection that has already been
+  * granted permission that created this object.  When done (or aborting), call
+  * releaseFetchDocumentPermission() to note the completion of the document
+  * fetch activity.
+  *@param currentTime is the current time, in ms. since epoch.
+  *@return the stream throttler to use to throttle the actual data access.
+  */
+  public IStreamThrottler obtainFetchDocumentPermission(long currentTime)
+    throws InterruptedException;
+  
+  /** Release permission to fetch a document.  Call this only when you
+  * called obtainFetchDocumentPermission() successfully earlier.
+  *@param currentTime is the current time, in ms. since epoch.
+  */
+  public void releaseFetchDocumentPermission(long currentTime);
+  
+}

Propchange: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IFetchThrottler.java
------------------------------------------------------------------------------
    svn:keywords = Id

Added: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java
URL: http://svn.apache.org/viewvc/manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java?rev=1550411&view=auto
==============================================================================
--- manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java (added)
+++ manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java Thu Dec 12 13:00:49 2013
@@ -0,0 +1,48 @@
+/* $Id$ */
+
+/**
+* Licensed to the Apache Software Foundation (ASF) under one or more
+* contributor license agreements. See the NOTICE file distributed with
+* this work for additional information regarding copyright ownership.
+* The ASF licenses this file to You under the Apache License, Version 2.0
+* (the "License"); you may not use this file except in compliance with
+* the License. You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+package org.apache.manifoldcf.core.interfaces;
+
+/** An IConnectionThrottler object is meant to be embedded in an InputStream.  It is not
+* thread-local, and does not require access to a thread context.  It thus also does not
+* throw ManifoldCFExceptions.  It is thus suitable for use in background threads, etc.
+* These objects are typically created by IFetchThrottler objects - they are not meant
+* to be created directly.
+*/
+public interface IStreamThrottler
+{
+  public static final String _rcsid = "@(#)$Id$";
+
+  /** Obtain permission to read a block of bytes.  This method may wait until it is OK to proceed.
+  * The throttle group, bin names, etc are already known
+  * to this specific interface object, so it is unnecessary to include them here.
+  *@param currentTime is the current time, in ms. since epoch.
+  *@param byteCount is the number of bytes to get permissions to read.
+  */
+  public void obtainReadPermission(long currentTime, int byteCount)
+    throws InterruptedException;
+    
+  /** Note the completion of the read of a block of bytes.  Call this after
+  * obtainReadPermission() was successfully called, and bytes were successfully read.
+  *@param currentTime is the current time, in ms. since epoch.
+  *@param origByteCount is the originally requested number of bytes to get permissions to read.
+  *@param actualByteCount is the number of bytes actually read.
+  */
+  public void releaseReadPermission(long currentTime, int origByteCount, int actualByteCount);
+  
+}

Propchange: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/interfaces/IStreamThrottler.java
------------------------------------------------------------------------------
    svn:keywords = Id

Modified: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/ConnectionThrottler.java
URL: http://svn.apache.org/viewvc/manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/ConnectionThrottler.java?rev=1550411&r1=1550410&r2=1550411&view=diff
==============================================================================
--- manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/ConnectionThrottler.java (original)
+++ manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/ConnectionThrottler.java Thu Dec 12 13:00:49 2013
@@ -30,6 +30,14 @@ public class ConnectionThrottler impleme
 
   /** The thread context */
   protected final IThreadContext threadContext;
+  
+  // Parameters of the current connection
+  
+  protected String throttleGroup = null;
+  protected IThrottleSpec throttleSpec = null;
+  protected String[] binNames = null;
+  
+  
   /** The actual static pool */
   protected final static Throttler throttler = new Throttler();
   
@@ -47,98 +55,26 @@ public class ConnectionThrottler impleme
   *@param throttleSpec is the throttle specification to use for the throttle group,
   *@param binNames is the set of bin names to throttle for, within the throttle group.
   *@param currentTime is the current time, in ms. since epoch.
+  *@return the fetch throttler to use when performing fetches from this connection.
   */
   @Override
-  public void obtainConnectionPermission(String throttleGroup,
+  public IFetchThrottler obtainConnectionPermission(String throttleGroup,
     IThrottleSpec throttleSpec, String[] binNames, long currentTime)
     throws ManifoldCFException
   {
-    throttler.obtainConnectionPermission(threadContext, throttleGroup,
-      throttleSpec, binNames, currentTime);
+    // MHL
+    return null;
   }
   
   /** Release permission to use a connection. This presumes that obtainConnectionPermission()
   * was called earlier in the same thread and was successful.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  @Override
-  public void releaseConnectionPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException
-  {
-    throttler.releaseConnectionPermission(threadContext, throttleGroup,
-      throttleSpec, binNames, currentTime);
-  }
-  
-  /** Get permission to fetch a document.  This grants permission to start
-  * fetching a single document.  When done (or aborting), call
-  * releaseFetchDocumentPermission() to note the completion of the document
-  * fetch activity.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  @Override
-  public void obtainFetchDocumentPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException
-  {
-    throttler.obtainFetchDocumentPermission(threadContext, throttleGroup,
-      throttleSpec, binNames, currentTime);
-  }
-  
-  /** Release permission to fetch a document.  Call this only when you
-  * called obtainFetchDocumentPermission() successfully earlier in the same
-  * thread.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  @Override
-  public void releaseFetchDocumentPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException
-  {
-    throttler.releaseFetchDocumentPermission(threadContext, throttleGroup,
-      throttleSpec, binNames, currentTime);
-  }
-  
-  /** Obtain permission to read a block of bytes.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  *@param byteCount is the number of bytes to get permissions to read.
-  */
-  @Override
-  public void obtainReadPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime, int byteCount)
-    throws ManifoldCFException
-  {
-    throttler.obtainReadPermission(threadContext, throttleGroup,
-      throttleSpec, binNames, currentTime, byteCount);
-  }
-    
-  /** Note the completion of the read of a block of bytes.  Call this after
-  * obtainReadPermission() was successfully called in the same thread.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
   *@param currentTime is the current time, in ms. since epoch.
-  *@param origByteCount is the originally requested number of bytes to get permissions to read.
-  *@param actualByteCount is the number of bytes actually read.
   */
   @Override
-  public void releaseReadPermission(String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime, int origByteCount, int actualByteCount)
+  public void releaseConnectionPermission(long currentTime)
     throws ManifoldCFException
   {
-    throttler.releaseReadPermission(threadContext, throttleGroup,
-      throttleSpec, binNames, currentTime, origByteCount, actualByteCount);
+    // MHL
   }
 
   /** Poll periodically.

Modified: manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/Throttler.java
URL: http://svn.apache.org/viewvc/manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/Throttler.java?rev=1550411&r1=1550410&r2=1550411&view=diff
==============================================================================
--- manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/Throttler.java (original)
+++ manifoldcf/branches/CONNECTORS-829/framework/core/src/main/java/org/apache/manifoldcf/core/throttler/Throttler.java Thu Dec 12 13:00:49 2013
@@ -23,6 +23,17 @@ import java.util.*;
 
 /** A Throttler object creates a virtual pool of connections to resources
 * whose access needs to be throttled in number, rate of use, and byte rate.
+* This code is modeled on the code for distributed connection pools, and is intended
+* to work in a similar manner.  Basically, a periodic assessment is done about what the
+* local throttling parameters should be (on a per-pool basis), and the local throttling
+* activities then adjust what they are doing based on the new parameters.  A service
+* model is used to keep track of which pools have what clients working with them.
+* This implementation has the advantage that:
+* (1) Only local throttling ever takes place on a method-by-method basis, which makes
+*   it possible to use throttling even in streams and background threads;
+* (2) Throttling resources are apportioned fairly, on average, between all the various
+*   cluster members, so it is unlikely that any persistent starvation conditions can
+*   arise.
 */
 public class Throttler
 {
@@ -58,12 +69,14 @@ public class Throttler
   *@param throttleSpec is the throttle specification to use for the throttle group,
   *@param binNames is the set of bin names to throttle for, within the throttle group.
   *@param currentTime is the current time, in ms. since epoch.
+  *@return the fetch throttler to use for fetches with the obtained connection.
   */
-  public void obtainConnectionPermission(IThreadContext threadContext, String throttleGroup,
+  public IFetchThrottler obtainConnectionPermission(IThreadContext threadContext, String throttleGroup,
     IThrottleSpec throttleSpec, String[] binNames, long currentTime)
     throws ManifoldCFException
   {
     // MHL
+    return null;
   }
   
   /** Release permission to use a connection. This presumes that obtainConnectionPermission()
@@ -80,71 +93,6 @@ public class Throttler
     // MHL
   }
   
-  /** Get permission to fetch a document.  This grants permission to start
-  * fetching a single document.  When done (or aborting), call
-  * releaseFetchDocumentPermission() to note the completion of the document
-  * fetch activity.
-  *@param threadContext is the thread context.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  public void obtainFetchDocumentPermission(IThreadContext threadContext, String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException
-  {
-    // MHL
-  }
-  
-  /** Release permission to fetch a document.  Call this only when you
-  * called obtainFetchDocumentPermission() successfully earlier in the same
-  * thread.
-  *@param threadContext is the thread context.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  */
-  public void releaseFetchDocumentPermission(IThreadContext threadContext, String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime)
-    throws ManifoldCFException
-  {
-    // MHL
-  }
-  
-  /** Obtain permission to read a block of bytes.
-  *@param threadContext is the thread context.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  *@param byteCount is the number of bytes to get permissions to read.
-  */
-  public void obtainReadPermission(IThreadContext threadContext, String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime, int byteCount)
-    throws ManifoldCFException
-  {
-    // MHL
-  }
-    
-  /** Note the completion of the read of a block of bytes.  Call this after
-  * obtainReadPermission() was successfully called in the same thread.
-  *@param threadContext is the thread context.
-  *@param throttleGroup is the throttle group name.
-  *@param throttleSpec is the throttle specification to use for the throttle group,
-  *@param binNames is the set of bin names describing this documemnt.
-  *@param currentTime is the current time, in ms. since epoch.
-  *@param origByteCount is the originally requested number of bytes to get permissions to read.
-  *@param actualByteCount is the number of bytes actually read.
-  */
-  public void releaseReadPermission(IThreadContext threadContext, String throttleGroup,
-    IThrottleSpec throttleSpec, String[] binNames, long currentTime, int origByteCount, int actualByteCount)
-    throws ManifoldCFException
-  {
-    // MHL
-  }
-
   /** Poll periodically.
   */
   public void poll(IThreadContext threadContext)