GH-2103 - Added documentation to clarify threading expectation when using Supplier

README.adoc

@@ -4,6 +4,7 @@ Manual changes to this file will be lost when it is generated again.
 Edit the files in the src/main/asciidoc/ directory instead.
 ////
 
+
 :jdkversion: 1.8
 :github-tag: master
 :github-repo: spring-cloud/spring-cloud-stream
@@ -108,29 +109,29 @@ Modify the `com.example.loggingconsumer.LoggingConsumerApplication` class to loo
 @SpringBootApplication
 public class LoggingConsumerApplication {
 
-	public static void main(String[] args) {
-		SpringApplication.run(LoggingConsumerApplication.class, args);
-	}
+    public static void main(String[] args) {
+        SpringApplication.run(LoggingConsumerApplication.class, args);
+    }
 
-	@Bean
-	public Consumer<Person> log() {
-	    return person -> {
-	        System.out.println("Received: " + person);
-	    };
-	}
+    @Bean
+    public Consumer<Person> log() {
+        return person -> {
+            System.out.println("Received: " + person);
+        };
+    }
 
-	public static class Person {
-		private String name;
-		public String getName() {
-			return name;
-		}
-		public void setName(String name) {
-			this.name = name;
-		}
-		public String toString() {
-			return this.name;
-		}
-	}
+    public static class Person {
+        private String name;
+        public String getName() {
+            return name;
+        }
+        public void setName(String name) {
+            this.name = name;
+        }
+        public String toString() {
+            return this.name;
+        }
+    }
 }
 ----
 
@@ -149,13 +150,13 @@ You should see following output:
 
 [source]
 ----
-	--- [ main] c.s.b.r.p.RabbitExchangeQueueProvisioner : declaring queue for inbound: input.anonymous.CbMIwdkJSBO1ZoPDOtHtCg, bound to: input
-	--- [ main] o.s.a.r.c.CachingConnectionFactory       : Attempting to connect to: [localhost:5672]
-	--- [ main] o.s.a.r.c.CachingConnectionFactory       : Created new connection: rabbitConnectionFactory#2a3a299:0/SimpleConnection@66c83fc8. . .
-	. . .
-	--- [ main] o.s.i.a.i.AmqpInboundChannelAdapter      : started inbound.input.anonymous.CbMIwdkJSBO1ZoPDOtHtCg
-	. . .
-	--- [ main] c.e.l.LoggingConsumerApplication         : Started LoggingConsumerApplication in 2.531 seconds (JVM running for 2.897)
+    --- [ main] c.s.b.r.p.RabbitExchangeQueueProvisioner : declaring queue for inbound: input.anonymous.CbMIwdkJSBO1ZoPDOtHtCg, bound to: input
+    --- [ main] o.s.a.r.c.CachingConnectionFactory       : Attempting to connect to: [localhost:5672]
+    --- [ main] o.s.a.r.c.CachingConnectionFactory       : Created new connection: rabbitConnectionFactory#2a3a299:0/SimpleConnection@66c83fc8. . .
+    . . .
+    --- [ main] o.s.i.a.i.AmqpInboundChannelAdapter      : started inbound.input.anonymous.CbMIwdkJSBO1ZoPDOtHtCg
+    . . .
+    --- [ main] c.e.l.LoggingConsumerApplication         : Started LoggingConsumerApplication in 2.531 seconds (JVM running for 2.897)
 ----
 
 Go to the RabbitMQ management console or any other RabbitMQ client and send a message to `input.anonymous.CbMIwdkJSBO1ZoPDOtHtCg`.
@@ -330,4 +331,4 @@ added after the original pull request but before a merge.
   message (where XXXX is the issue number).
 
 
-// ======================================================================================
+// ======================================================================================

docs/src/main/asciidoc/spring-cloud-stream.adoc

@@ -495,6 +495,18 @@ the framework will split the returning sending out each item as an individual me
 he desired behavior you can set it to `false` at which point such supplier will simply return
 the produced Flux without splitting it.
 
+
+====== Supplier & threading
+
+NOTE: As you have learned by now, unlike `Function` and `Consumer`, which are triggered by an event (they have input data), `Supplier` does not have
+any input and thus triggered by a different mechanism - _poller_, which may have an unpredictable threading mechanism. And while the details of the 
+threading mechanism most of the time are not relevant to the downstream execution of the function it may present an issue in certain cases 
+especially with integrated frameworks that may have certain expectations to thread affinity. For example, https://spring.io/projects/spring-cloud-sleuth[Spring Cloud Sleuth] which relies 
+on tracing data stored in thread local.
+For those cases we have another mechanism via `StreamBridge`, where user has more control over threading mechanism. You can get more details 
+in <<Sending arbitrary data to an output (e.g. Foreign event-driven sources)>> section.
+
+
 ===== Consumer (Reactive)
 
 Reactive `Consumer` is a little bit special because it has a void return type, leaving framework with no reference to subscribe to.