Skip to content

Commit

Permalink
Update README.md and ReleaseNotes.md
Browse files Browse the repository at this point in the history
Async promises are now pooled, so removed that section from Async/Await pitfalls.
  • Loading branch information
timcassell authored and Tim committed Sep 30, 2020
1 parent 13c74a3 commit fd36e38
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 13 deletions.
20 changes: 7 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,11 @@ This library took inspiration from <a href="https://developer.mozilla.org/en-US/

## Latest Updates

### v 0.10
### v 0.11.0

- Added `Proto.Promises.{CancelationSource, CancelationToken, CancelationRegistration}` structs which can be used for synchronous cancelation callbacks.
- Added optional `CancelationToken` parameter to `Promise.{Then, Catch, CatchCancelation, ContinueWith, Progress, Sequence, NewDeferred}`.
- Removed `Promise.{Cancel, ThenDuplicate}`.
- Changed Deferreds to structs with an implicit cast to DeferredBase (`DeferredBase.ToDeferred(<T>)()` to cast back explicitly).
- Change `Deferred.Reject(null)` to convert to a `NullReferenceException` on any `T`. This means `Promise.Catch<T>` will never give a null value. This more closely matches normal `throw null;` behavior.
- Added object pooling for allocation-free `async Promise` functions.
- Fixed causality traces in async Promise functions.
- Fixed aggregate exception not capturing the unhandled exceptions.

See <a href="https://github.com/timcassell/ProtoPromise/blob/master/ReleaseNotes.md">Release Notes</a> for detailed changes.

Expand Down Expand Up @@ -633,13 +631,9 @@ Promises are awaitable. This means you can use the `await` keyword to wait for t

There are some pitfalls to using the async and await features.

If you've used Tasks, you are probably used to them throwing the exception that actually occurred instead of an exception wrapper. Promises throw a wrapper exception because the promise can be rejected with _any_ value, not just an exception. It also contains the full causality trace.
If you've used Tasks, you are probably used to them throwing the exception that actually occurred instead of an exception wrapper. Promises throw a wrapper exception because the promise can be rejected with _any_ value, not just an exception. It also contains the full causality trace. At least you can still catch `OperationCanceledException` to catch cancelations the same way as Tasks (and, unlike with the normal `Promise.Then` API where catching cancelations is optional, you probably _should_ catch cancelation exceptions in an async function).

The other thing, and this is more of an issue than exceptions, is that you can't report progress to the promise returned from the async function. This is probably why the designers of Tasks chose to use `Progress<T>` passed into functions instead of implementing it directly into Tasks. Therefore, if you use async Promise functions, I recommend you disable promise progress (See [Compiler Options](#compiler-options)).

Another issue is that, while promises don't need to create extra allocations every time if object pooling is enabled, `async Promise` functions do not use the same pooling trick. Because of that, `async Promise` functions will almost always allocate when they are called (the exception to this is when they complete synchronously).

At least you can still catch `OperationCanceledException` to catch cancelations the same way as Tasks (and, unlike with the normal `Promise.Then` API where catching cancelations is optional, you probably _should_ catch cancelation exceptions in an async function).
The other thing, and this is more of an issue than exception handling, is that you can't report progress to the promise returned from the async function. This is probably why the designers of Tasks chose to use `Progress<T>` passed into functions instead of implementing it directly into Tasks. Therefore, if you use async Promise functions, I recommend you disable promise progress (See [Compiler Options](#compiler-options)).

## Additional Information

Expand Down Expand Up @@ -722,4 +716,4 @@ IEnumerator GetAndAssignTexture(Image image, string url)
image.sprite = sprite;
}
}
```
```
20 changes: 20 additions & 0 deletions ReleaseNotes.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,25 @@
# Release Notes

## v 0.11.0 - September 30, 2020

Optimizations:

- Added object pooling for allocation-free async Promise functions.
- Removed LitePromises, using DeferredPromises for Promise.Resolved/Rejected/Canceled instead to reduce amount of code.

Bug Fixes:

- Fixed causality traces in async Promise functions.
- Fixed aggregate exception not capturing the unhandled exceptions.
- Fixed PromiseMethodBuilders for async Promise functions with the IL2CPP compiler. (v0.10.2)

Misc:

- Added message to unhandled exceptions, when not in DEBUG mode, to explain how to see causality traces.
- Added implicit cast operators for `Promise.Deferred` -> `Promise.DeferredBase` and `Promise<T>.Deferred` -> `Promise.DeferredBase`. (v0.10.1)
- Ignore Internal functions and PromiseYielder.Routines in causality traces. (v0.10.2)
- Include causality trace from invalid returned promise. (v0.10.2)

## v 0.10 - August 21, 2020

API changes:
Expand Down

0 comments on commit fd36e38

Please sign in to comment.