-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add support for non-Tuple iterators, improve docs and tests
- Loading branch information
1 parent
91a30eb
commit 6efc2a5
Showing
18 changed files
with
1,857 additions
and
441 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
The following autogenerated tables contain a representative set of potential use | ||
cases for this package, along with measurements that summarize each case's | ||
performance, compilation, and memory usage: | ||
- run time (best of several trial measurements) | ||
- compilation time (as reported by the compiler) | ||
- overall level of optimization (type stability, constant propagation, etc.) and | ||
allocations during run time (as reported by the garbage collector) | ||
- total allocations during compilation and first run (as reported by the garbage | ||
collector and, when possible, the Julia process's resident set size estimator) | ||
|
||
The rows of the tables are highlighted as follows: | ||
- ```@raw html | ||
<span style="color:darkturquoise">light blue </span> | ||
``` | ||
indicates an improvement in performance due to better optimization and either | ||
an improvement or no change in compilation time and total allocations | ||
- ```@raw html | ||
<span style="color:royalblue">dark blue </span> | ||
``` | ||
indicates an improvement in performance due to better optimization and either | ||
slower compilation or more total allocations | ||
- ```@raw html | ||
<span style="color:mediumseagreen">green </span> | ||
``` | ||
indicates either faster run time or fewer allocations during run time and | ||
either an improvement or no change in compilation time and total allocations | ||
- ```@raw html | ||
<span style="color:khaki">yellow </span> | ||
``` | ||
indicates either faster run time or fewer allocations during run time and | ||
either slower compilation or more total allocations | ||
- ```@raw html | ||
<span style="color:mediumorchid">magenta </span> | ||
``` | ||
indicates no change in performance and either an improvement or no change in | ||
compilation time and total allocations | ||
- ```@raw html | ||
<span style="color:silver">light gray </span> | ||
``` | ||
indicates no change in performance and either faster compilation with more | ||
total allocations or slower compilation with fewer total allocations | ||
- ```@raw html | ||
<span style="color:gray">dark gray </span> | ||
``` | ||
indicates no change in performance and no change in compilation time and total | ||
allocations | ||
- ```@raw html | ||
<span style="color:indianred">red </span> | ||
``` | ||
indicates a deterioration in performance, or no change in performance and | ||
either slower compilation or more total allocations | ||
|
||
Rows highlighted in gray present no clear advantage to unrolling, while those | ||
highlighted in red present a clear disadvantage. It is recommended that you only | ||
unroll when your use case is similar to a row in one of the remaining | ||
categories, each of which demonstrates some advantage to unrolling. | ||
|
||
The tables are also printed out by this package's test suite, so they can be | ||
compared across different operating systems by consulting the | ||
[CI pipeline](https://github.com/CliMA/UnrolledUtilities.jl/actions/workflows/ci.yml). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,55 @@ | ||
```@meta | ||
CurrentModule = UnrolledUtilities | ||
``` | ||
|
||
## Unrollable Iterator Interface | ||
|
||
The functions exported by this package can be used with any statically sized | ||
iterators, as long as those iterators are compatible with following interface: | ||
|
||
```@docs | ||
generic_getindex | ||
output_type_for_promotion | ||
AmbiguousOutputType | ||
NoOutputType | ||
ConditionalOutputType | ||
output_promote_rule | ||
constructor_from_tuple | ||
``` | ||
|
||
## Extending the Interface | ||
|
||
To unroll over a statically sized iterator of some user-defined type `T`, follow | ||
these steps: | ||
- Add a method for either `getindex(::T, n)` or `generic_getindex(::T, n)` | ||
- If every unrolled function that needs to construct an iterator when given an | ||
iterator of type `T` can return a `Tuple` instead, stop here; otherwise, to | ||
return a non-Tuple iterator whenever possible, follow these steps: | ||
- Add a method for `output_type_for_promotion(::T) = O`, where `O` can be | ||
`T`, a supertype of `T`, or some other `Type` or `AmbiguousOutputType` | ||
- If an output of type `O` can be used together with an output of type `O′`, | ||
add a method for `output_promote_rule(O, O′)` | ||
- If an output of type `O` can be efficiently constructed from a `Tuple`, | ||
add a method for `constructor_from_tuple(O)`; otherwise, add a method for | ||
each unrolled function that can efficiently generate an output of type `O` | ||
without temporarily storing it as a `Tuple` | ||
|
||
## Internals | ||
|
||
*TODO: This is still under development.* | ||
|
||
The unrolled functions have been written in a way that makes them very | ||
likely to get fully optimized out through constant propagation when the | ||
iterators have singleton element types (and when the result of calling `f` | ||
and/or `op` on these elements is inferrable). However, they can also be much | ||
more expensive to compile than their counterparts from `Base` and | ||
`Base.Iterators`, in which case they should not be used unless there is a clear | ||
performance benefit. Two notable exceptions to this are `unrolled_take` and | ||
`unrolled_drop`, which are faster to compile than their non-static versions. | ||
|
||
```@docs | ||
rec_unroll | ||
``` | ||
|
||
For more information, see the benchmarks for | ||
[Generative vs. Recursive Unrolling](@ref). |
Oops, something went wrong.