flume-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From arv...@apache.org
Subject svn commit: r1303665 - in /incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume: Channel.java PollableSource.java Sink.java SinkProcessor.java Source.java Transaction.java conf/Configurable.java
Date Thu, 22 Mar 2012 06:45:42 GMT
Author: arvind
Date: Thu Mar 22 06:45:42 2012
New Revision: 1303665

URL: http://svn.apache.org/viewvc?rev=1303665&view=rev
Log:
FLUME-1026. Document Thread Safety Guarantees.

(Juhani Connolly via Arvind Prabhakar)

Modified:
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Channel.java
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/PollableSource.java
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Sink.java
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/SinkProcessor.java
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Source.java
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Transaction.java
    incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/conf/Configurable.java

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Channel.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Channel.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Channel.java (original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Channel.java Thu Mar
22 06:45:42 2012
@@ -41,6 +41,11 @@ import org.apache.flume.lifecycle.Lifecy
  * Channels are associated with unique {@linkplain NamedComponent names} that
  * can be used for separating configuration and working namespaces.
  * </p>
+ * <p>
+ * Channels must be thread safe, protecting any internal invariants as no
+ * guarantees are given as to when and by how many sources/sinks they may
+ * be simultaneously accessed by.
+ * </p>
  *
  * @see org.apache.flume.Source
  * @see org.apache.flume.Sink

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/PollableSource.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/PollableSource.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/PollableSource.java
(original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/PollableSource.java
Thu Mar 22 06:45:42 2012
@@ -29,7 +29,22 @@ import org.apache.flume.source.EventDriv
  * @see org.apache.flume.source.EventDrivenSourceRunner
  */
 public interface PollableSource extends Source {
-
+  /**
+   * <p>
+   * Attempt to pull an item from the source, sending it to the channel.
+   * </p>
+   * <p>
+   * When driven by an {@link EventDrivenSourceRunner} process is guaranteed
+   * to be called only by a single thread at a time, with no concurrency.
+   * Any other mechanism driving a pollable source must follow the same
+   * semantics.
+   * </p>
+   * @return {@code READY} if one or more events were created from the source.
+   * {@code BACKOFF} if no events could be created from the source.
+   * @throws EventDeliveryException If there was a failure in delivering to
+   * the attached channel, or if a failure occurred in acquiring data from
+   * the source.
+   */
   public Status process() throws EventDeliveryException;
 
   public static enum Status {

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Sink.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Sink.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Sink.java (original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Sink.java Thu Mar 22
06:45:42 2012
@@ -35,6 +35,11 @@ import org.apache.flume.lifecycle.Lifecy
  * Sinks are associated with unique names that can be used for separating
  * configuration and working namespaces.
  * </p>
+ * <p>
+ * While the {@link Sink#process()} call is guaranteed to only be accessed
+ * by a single thread, other calls may be concurrently accessed and should
+ * thus be protected.
+ * </p>
  *
  * @see org.apache.flume.Channel
  * @see org.apache.flume.SinkProcessor

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/SinkProcessor.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/SinkProcessor.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/SinkProcessor.java
(original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/SinkProcessor.java
Thu Mar 22 06:45:42 2012
@@ -24,8 +24,15 @@ import org.apache.flume.conf.Configurabl
 import org.apache.flume.lifecycle.LifecycleAware;
 
 /**
- * <p>Interface for a device that allows abstraction of the behavior of multiple
- * sinks, always assigned to a SinkRunner</p>
+ * <p>
+ * Interface for a device that allows abstraction of the behavior of multiple
+ * sinks, always assigned to a SinkRunner
+ * </p>
+ * <p>
+ * A sink processors {@link SinkProcessor#process()} method will only be
+ * accessed by a single runner thread. However configuration methods
+ * such as {@link Configurable#configure} may be concurrently accessed.
+ *
  * @see org.apache.flume.Sink
  * @see org.apache.flume.SinkRunner
  * @see org.apache.flume.sink.SinkGroup

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Source.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Source.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Source.java (original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Source.java Thu Mar
22 06:45:42 2012
@@ -34,6 +34,10 @@ import org.apache.flume.lifecycle.Lifecy
  * be used for separating configuration and working namespaces.
  * </p>
  *
+ * <p>
+ * No guarantees are given regarding thread safe access.
+ * </p>
+ *
  * @see org.apache.flume.Channel
  * @see org.apache.flume.Sink
  */

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Transaction.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Transaction.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Transaction.java (original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/Transaction.java Thu
Mar 22 06:45:42 2012
@@ -17,6 +17,9 @@
  */
 package org.apache.flume;
 
+import org.apache.flume.channel.BasicChannelSemantics;
+import org.apache.flume.channel.BasicTransactionSemantics;
+
 /**
  * <p>Provides the transaction boundary while accessing a channel.</p>
  * <p>A <tt>Transaction</tt> instance is used to encompass channel access
@@ -40,6 +43,11 @@ package org.apache.flume;
  * <p>Depending upon the implementation of the channel, the transaction
  * semantics may be strong, or best-effort only.</p>
  *
+ * <p>
+ * Transactions must be thread safe. To provide  a guarantee of thread safe
+ * access to Transactions, see {@link BasicChannelSemantics} and
+ * {@link  BasicTransactionSemantics}.
+ *
  * @see org.apache.flume.Channel
  */
 public interface Transaction {

Modified: incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/conf/Configurable.java
URL: http://svn.apache.org/viewvc/incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/conf/Configurable.java?rev=1303665&r1=1303664&r2=1303665&view=diff
==============================================================================
--- incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/conf/Configurable.java
(original)
+++ incubator/flume/trunk/flume-ng-core/src/main/java/org/apache/flume/conf/Configurable.java
Thu Mar 22 06:45:42 2012
@@ -21,8 +21,26 @@ package org.apache.flume.conf;
 
 import org.apache.flume.Context;
 
+/**
+ * <p>
+ * Any class marked as Configurable may have a context including its
+ * sub-configuration passed to it, requesting it configure itself.
+ * </p>
+ */
 public interface Configurable {
-
+  /**
+   * <p>
+   * Request the implementing class to (re)configure itself.
+   * </p>
+   * <p>
+   * When configuration parameters are changed, they must be
+   * reflected by the component asap.
+   * </p>
+   * <p>
+   * There are no thread safety guarrantees on when configure might be called.
+   * </p>
+   * @param context
+   */
   public void configure(Context context);
 
 }



Mime
View raw message