Can merging of multiple sources be prioritized? (#22864)

* Adding MergePrioritized graph stage

* Adding MergePrioritized in akka docs

* Adding suggested documentation of MergePrioritized in akka docs

* Adding thread safe random number generator ThreadLocalRandom

* fixing documentation for MergePrioritized

* Refactoring selectNextElement() in MergePrioritized for less memory allocations

* Removing extra parameter in MergePrioritized and using SplittableRandom

* Refactoring GraphMergePrioritizedSpec

* Changes for paradox migration

* Optimized a few methods in MergePrioritized (#22864)

* increased no of elements in source in GraphMergePrioritizedSpec (#22864)

akka-docs/src/main/paradox/java/stream/stream-graphs.md

@@ -31,6 +31,7 @@ Akka Streams currently provide these junctions (for a detailed list see @ref:[st
 
     * `Merge<In>` – *(N inputs , 1 output)* picks randomly from inputs pushing them one by one to its output
     * `MergePreferred<In>` – like `Merge` but if elements are available on `preferred` port, it picks from it, otherwise randomly from `others`
+    * `MergePrioritized<In>` – like `Merge` but if elements are available on all input ports, it picks from them randomly based on their `priority`
     * `ZipWith<A,B,...,Out>` – *(N inputs, 1 output)* which takes a function of N inputs that given a value for each input emits 1 output element
     * `Zip<A,B>` – *(2 inputs, 1 output)* is a `ZipWith` specialised to zipping input streams of `A` and `B` into a `Pair(A,B)` tuple stream
     * `Concat<A>` – *(2 inputs, 1 output)* concatenates two streams (first consume one, then the second one)

akka-docs/src/main/paradox/scala/stream/stages-overview.md

@@ -1568,6 +1568,19 @@ Merge multiple sources. Prefer one source if all sources has elements ready.
 
 ---------------------------------------------------------------
 
+### mergePrioritized
+
+Merge multiple sources. Prefer sources depending on priorities if all sources has elements ready. If a subset of all
+sources has elements ready the relative priorities for those sources are used to prioritise.
+
+**emits** when one of the inputs has an element available, preferring inputs based on their priorities if multiple have elements available
+
+**backpressures** when downstream backpressures
+
+**completes** when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting `eagerComplete=true`.)
+
+---------------------------------------------------------------
+
 ### zip
 
 Combines elements from each of multiple sources into @scala[tuples] @java[*Pair*] and passes the @scala[tuples] @java[pairs] downstream.

akka-docs/src/main/paradox/scala/stream/stream-flows-and-basics.md

@@ -352,5 +352,5 @@ such as `Zip` however *do guarantee* their outputs order, as each output element
 been signalled already – thus the ordering in the case of zipping is defined by this property.
 
 If you find yourself in need of fine grained control over order of emitted elements in fan-in
-scenarios consider using `MergePreferred` or `GraphStage` – which gives you full control over how the
-merge is performed.
+scenarios consider using `MergePreferred`, `MergePrioritized` or `GraphStage` – which gives you full control over how the
+merge is performed.

akka-docs/src/main/paradox/scala/stream/stream-graphs.md

@@ -31,6 +31,7 @@ Akka Streams currently provide these junctions (for a detailed list see @ref:[st
 
     * `Merge[In]` – *(N inputs , 1 output)* picks randomly from inputs pushing them one by one to its output
     * `MergePreferred[In]` – like `Merge` but if elements are available on `preferred` port, it picks from it, otherwise randomly from `others`
+    * `MergePrioritized[In]` – like `Merge` but if elements are available on all input ports, it picks from them randomly based on their `priority`
     * `ZipWith[A,B,...,Out]` – *(N inputs, 1 output)* which takes a function of N inputs that given a value for each input emits 1 output element
     * `Zip[A,B]` – *(2 inputs, 1 output)* is a `ZipWith` specialised to zipping input streams of `A` and `B` into an `(A,B)` tuple stream
     * `Concat[A]` – *(2 inputs, 1 output)* concatenates two streams (first consume one, then the second one)