You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flume.apache.org by ar...@apache.org on 2012/03/22 07:45:42 UTC
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
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);
}