You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
By default the `Promises` static methods use an instance of `PromiseFactory`. This `PromiseFactory` interface has various implementations.
10
+
The default implementation is link:{api}/org/grails/async/factory/future/CachedThreadPoolPromiseFactory.html[CachedThreadPoolPromiseFactory] which uses a thread pool that will create threads as needed (the same as `java.util.concurrent.Executors.newCachedThreadPool()`)
11
+
12
+
However, the design of the promises framework is such that you can swap out the underlying implementation for your own or one of the pre-supported implementations.
13
+
For example to use RxJava 1.x simply add the RxJava dependency to `build.gradle`:
Copy file name to clipboardExpand all lines: src/main/docs/guide/events.adoc
+8-6Lines changed: 8 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,25 @@
1
-
Grails 3.3 introduces a new Events API that replaces the previous implementation that was based on Reactor 2.x (which is no longer maintained and deprecated).
1
+
This project introduces a new Events API that replaces the previous implementation that was based on Reactor 2.x (which is no longer maintained and deprecated).
2
2
3
-
In Grails 3.3 and above a new link:{api}/grails/events/bus/EventBus.html[EventBus] abstraction has been introduced. Like the `PromiseFactory` notion, there are implementations of the `EventBus` interface for common asynchronous frameworks like GPars and RxJava.
3
+
The Events framework introduces a new link:{api}/grails/events/bus/EventBus.html[EventBus] abstraction.
4
+
Like the `PromiseFactory` notion, there are implementations of the `EventBus` interface for common asynchronous frameworks like GPars and RxJava.
4
5
5
-
To use the Grails Events abstraction you should add a dependency on the `events` plugin to your `build.gradle` file:
6
+
To use the Events abstraction you should add a dependency on the `events` plugin to your `build.gradle` file:
If no asynchronous framework in present on the classpath then by default Grails creates an EventBus based off of the currently active `PromiseFactory`. The default implementation is link:{api}/org/grails/async/factory/future/CachedThreadPoolPromiseFactory.html[CachedThreadPoolPromiseFactory] which uses a thread pool that will create threads as needed (the same as `java.util.concurrent.Executors.newCachedThreadPool()`).
14
+
If no asynchronous framework in present on the classpath then by default Grace creates an EventBus based off of the currently active `PromiseFactory`.
15
+
The default implementation is link:{api}/org/grails/async/factory/future/CachedThreadPoolPromiseFactory.html[CachedThreadPoolPromiseFactory] which uses a thread pool that will create threads as needed (the same as `java.util.concurrent.Executors.newCachedThreadPool()`).
14
16
15
17
If you wish to use a popular async framework such as RxJava as the `EventBus` implementation then you will need to add the appropriate dependency. For example for RxJava 1.x:
With modern hardware featuring multiple cores, many programming languages have been adding asynchronous, parallel programming APIs, Groovy being no exception.
1
+
This project contains APIs and libraries that integrate Grace with various asynchronous libraries and frameworks such as https://github.com/GPars/GPars[GPars] and https://github.com/ReactiveX/RxJava/tree/1.x[RxJava], https://github.com/ReactiveX/RxJava/releases/tag/v2.2.21[RxJava2], https://github.com/ReactiveX/RxJava/releases[RxJava3].
2
2
3
-
Added Grails 2.3 and since 3.3 an external project, the Async features of Grails aim to simplify concurrent programming within the framework and include the concept of Promises and a unified event model.
3
+
The Async framework aim to simplify concurrent programming within the framework and include the concept of Promises and a unified event model,
4
+
and the Events framework provides a new Events API that replaces the previous implementation that was based on Reactor https://github.com/reactor/reactor/tree/v2.0.8.RELEASE[2.x] (which is no longer maintained and deprecated).
Copy file name to clipboardExpand all lines: src/main/docs/guide/promises.adoc
+16-17Lines changed: 16 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,16 @@
1
1
A Promise is a concept being embraced by many concurrency frameworks. They are similar to `java.util.concurrent.Future` instances, but include a more user friendly exception handling model, useful features like chaining and the ability to attach listeners.
2
2
3
-
To use the Grails Promise abstraction you should add a dependency on the `async` plugin to your `build.gradle` file:
3
+
To use the `Promise` abstraction you should add a dependency on the `async` plugin to your `build.gradle` file:
In Grails the `grails.async.Promises` class provides the entry point to the Promise API:
13
+
The `grails.async.Promises` class provides the entry point to the Promise API:
15
14
16
15
[source,groovy]
17
16
----
@@ -72,14 +71,16 @@ def result = p.get(1,MINUTES)
72
71
73
72
=== The PromiseFactory Interface
74
73
75
-
By default the `Promises` static methods use an instance of `PromiseFactory`. This `PromiseFactory` interface has various implementations. The default implementation is link:{api}/org/grails/async/factory/future/CachedThreadPoolPromiseFactory.html[CachedThreadPoolPromiseFactory] which uses a thread pool that will create threads as needed (the same as `java.util.concurrent.Executors.newCachedThreadPool()`)
74
+
By default the `Promises` static methods use an instance of `PromiseFactory`. This `PromiseFactory` interface has various implementations.
75
+
The default implementation is link:{api}/org/grails/async/factory/future/CachedThreadPoolPromiseFactory.html[CachedThreadPoolPromiseFactory] which uses a thread pool that will create threads as needed (the same as `java.util.concurrent.Executors.newCachedThreadPool()`)
76
76
77
-
However, the design of the Grails promises framework is such that you can swap out the underlying implementation for your own or one of the pre-supported implementations. For example to use RxJava 1.x simply add the RxJava dependency to `build.gradle`:
77
+
However, the design of the promises framework is such that you can swap out the underlying implementation for your own or one of the pre-supported implementations.
78
+
For example to use RxJava 1.x simply add the RxJava dependency to `build.gradle`:
With the above in place RxJava 1.x will be used to create `Promise` instances.
@@ -110,7 +111,8 @@ The following table summarizes the available implementation and the dependency t
110
111
You can also override the `grails.async.PromiseFactory` class used by `Promises` by setting the `promiseFactory` static field.
111
112
112
113
113
-
One common use case for this is unit testing, typically you do not want promises to execute asynchronously during unit tests, as this makes tests harder to write. For this purpose Grails ships with a `org.grails.async.factory.SynchronousPromiseFactory` instance that makes it easier to test promises:
114
+
One common use case for this is unit testing, typically you do not want promises to execute asynchronously during unit tests, as this makes tests harder to write.
115
+
For this purpose Grails ships with a `org.grails.async.factory.SynchronousPromiseFactory` instance that makes it easier to test promises:
114
116
115
117
[source,groovy]
116
118
----
@@ -120,11 +122,11 @@ import grails.async.*
120
122
Promises.promiseFactory = new SynchronousPromiseFactory()
121
123
----
122
124
123
-
Using the `PromiseFactory` mechanism it is theoretically possible to plug in other concurrency libraries into the Grails framework. For this you need to override the two interfaces `grails.async.Promise` and `grails.async.PromiseFactory`.
125
+
Using the `PromiseFactory` mechanism it is theoretically possible to plug in other concurrency libraries into the Grace framework.
126
+
For this you need to override the two interfaces `grails.async.Promise` and `grails.async.PromiseFactory`.
124
127
125
128
=== Promise Chaining
126
129
127
-
128
130
It is possible to chain several promises and wait for the chain to complete using the `then` method:
129
131
130
132
[source,groovy]
@@ -147,8 +149,7 @@ If an exception occurs at any point in the chain it will be propagated back to t
147
149
148
150
=== Promise Lists and Maps
149
151
150
-
151
-
Grails' async API also features the concept of a promise lists and maps. These are represented by the `grails.async.PromiseList` and `grails.async.PromiseMap` classes respectively.
152
+
The Async API also features the concept of a promise lists and maps. These are represented by the `grails.async.PromiseList` and `grails.async.PromiseMap` classes respectively.
152
153
153
154
The easiest way to create a promise list or map is via the `tasks` method of the `Promises` class:
154
155
@@ -176,11 +177,10 @@ list.onComplete { List results ->
176
177
}
177
178
----
178
179
179
-
NOTE: The `PromiseList` class does not implement the java.util.List interface, but instead returns a java.util.List from the get() method
180
+
NOTE: The `PromiseList` class does not implement the `java.util.List` interface, but instead returns a `java.util.List` from the `get()` method.
180
181
181
182
Working with `PromiseMap` instances is largely similar. Again you can either use the `tasks` method:
It is quite common to require both synchronous and asynchronous versions of the same API. Developing both can result in a maintenance problem as typically the asynchronous API would simply delegate to the synchronous version.
213
+
It is quite common to require both synchronous and asynchronous versions of the same API.
214
+
Developing both can result in a maintenance problem as typically the asynchronous API would simply delegate to the synchronous version.
216
215
217
216
The `DelegateAsync` transformation is designed to mitigate this problem by transforming any synchronous API into an asynchronous one.
To make it easier for users to use and upgrade, Plugin adopts a version policy consistent with the https://github.com/graceframework/grace-framework[Grace Framework].
0 commit comments