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
* Add patch version to conform to full semantic versioning spec and build LIBDIVIDE_VERSION from the version components
* GitHub Workflow to create a release PR
* Add GH acation to create a draft release
* Generate a run summary that will be displayed in the GH UI.
* Update documentation: separate out development instructions from usage and use relative links everywhere.
* Typos, prompts, alignment
* Embed version string directly in libdivide.h
* Remove space from filename
* Example commands: remove prompts for easier copy/paste, use 'pwsh' tag for better syntax highlighting
* Add back original doc from ridiculousfish
* Move doc to RELEASE.md
* Improve release type descriptions
* Additional release process details.
* Fix typo
---------
Co-authored-by: Kim Walisch <[email protected]>
vector division which provides an even larger speedup. You can test how much
19
-
speedup you can achieve on your CPU using the [benchmark](#benchmark-program)
20
-
program.
6
+
```libdivide.h``` is a header-only C/C++ library for optimizing integer division. Integer division is one of the slowest instructions on most CPUs e.g. on current x64 CPUs a 64-bit integer division has a latency of up to 90 clock cycles whereas a multiplication has a latency of only 3 clock cycles. libdivide allows you to replace expensive integer division instructions by a sequence of shift, add and multiply instructions that will calculate the integer division much faster.
21
7
22
-
libdivide is compatible with 8-bit microcontrollers, such as the AVR series: [the CI build includes a AtMega2560 target](test/avr/readme.md). Since low end hardware such as this often do not include a hardware divider, libdivide is particularly useful. In addition to the runtime [C](https://github.com/ridiculousfish/libdivide/blob/master/doc/C-API.md) & [C++](https://github.com/ridiculousfish/libdivide/blob/master/doc/CPP-API.md) APIs, a set of [predefined macros](constant_fast_div.h) and [templates](constant_fast_div.hpp) is included to speed up division by 16-bit constants: division by a 16-bit constant is [not optimized by avr-gcc on 8-bit systems](https://stackoverflow.com/questions/47994933/why-doesnt-gcc-or-clang-on-arm-use-division-by-invariant-integers-using-multip).
8
+
On current CPUs you can get a **speedup of up to 10x** for 64-bit integer division and a speedup of up to to 5x for 32-bit integer division when using libdivide. libdivide also supports [SSE2](https://en.wikipedia.org/wiki/SSE2), [AVX2](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) and [AVX512](https://en.wikipedia.org/wiki/Advanced_Vector_Extensions) vector division which provides an even larger speedup. You can test how much speedup you can achieve on your CPU using the [benchmark](#benchmark-program) program.
9
+
10
+
libdivide is compatible with 8-bit microcontrollers, such as the AVR series: [the CI build includes a AtMega2560 target](test/avr/readme.md). Since low end hardware such as this often do not include a hardware divider, libdivide is particularly useful. In addition to the runtime [C](doc/C-API.md) & [C++](doc/CPP-API.md) APIs, a set of [predefined macros](constant_fast_div.h) and [templates](constant_fast_div.hpp) is included to speed up division by 16-bit constants: division by a 16-bit constant is [not optimized by avr-gcc on 8-bit systems](https://stackoverflow.com/questions/47994933/why-doesnt-gcc-or-clang-on-arm-use-division-by-invariant-integers-using-multip).
23
11
24
12
See https://libdivide.com for more information on libdivide.
25
13
26
-
# C++ example
14
+
##C++ example
27
15
28
16
The first code snippet divides all integers in a vector using integer division.
29
17
This is slow as integer division is at least one order of magnitude slower than
@@ -60,7 +48,7 @@ Generally libdivide will give a significant speedup if:
60
48
* The divisor is only known at runtime
61
49
* The divisor is reused multiple times e.g. in a loop
62
50
63
-
# C example
51
+
##C example
64
52
65
53
You first need to generate a libdivide divider using one of the ```libdivide_*_gen``` functions (```*```: ```s32```, ```u32```, ```s64```, ```u64```)
66
54
which can then be used to compute the actual integer division using the
* [Template Based Invariant Division](constant_fast_div.hpp)
88
76
89
-
# Branchfull vs branchfree
77
+
## Branchfull vs branchfree
90
78
91
79
The default libdivide divider makes use of
92
-
[branches](https://en.wikipedia.org/wiki/Branch_(computer_science)) to compute the integer
93
-
division. When the same divider is used inside a hot loop as in the C++ example section the
94
-
CPU will accurately predict the branches and there will be no performance slowdown. Often
95
-
the compiler is even able to move the branches outside the body of the loop hence
96
-
completely eliminating the branches, this is called loop-invariant code motion.
97
-
98
-
libdivide also has a branchfree divider type which computes the integer division without
99
-
using any branch instructions. The branchfree divider generally uses a few more instructions
100
-
than the default branchfull divider. The main use case for the branchfree divider is when
101
-
you have an array of different divisors and you need to iterate over the divisors. In this
102
-
case the default branchfull divider would exhibit poor performance as the CPU won't be
103
-
able to correctly predict the branches.
80
+
[branches](https://en.wikipedia.org/wiki/Branch_(computer_science)) to compute the integer division. When the same divider is used inside a hot loop as in the C++ example section the CPU will accurately predict the branches and there will be no performance slowdown. Often the compiler is even able to move the branches outside the body of the loop hence completely eliminating the branches, this is called loop-invariant code motion.
81
+
82
+
libdivide also has a branchfree divider type which computes the integer division without using any branch instructions. The branchfree divider generally uses a few more instructions than the default branchfull divider. The main use case for the branchfree divider is when you have an array of different divisors and you need to iterate over the divisors. In this case the default branchfull divider would exhibit poor performance as the CPU won't be able to correctly predict the branches.
104
83
105
84
```C++
106
85
#include "libdivide.h"
@@ -124,14 +103,12 @@ Caveats of branchfree divider:
vector division on x86 and x64 CPUs. In the example below we divide the packed 32-bit
133
-
integers inside an AVX512 vector using libdivide. libdivide supports 32-bit and 64-bit
134
-
vector division for both signed and unsigned integers.
111
+
vector division on x86 and x64 CPUs. In the example below we divide the packed 32-bit integers inside an AVX512 vector using libdivide. libdivide supports 32-bit and 64-bit vector division for both signed and unsigned integers.
135
112
136
113
```C++
137
114
#include"libdivide.h"
@@ -153,7 +130,7 @@ Note that you need to define one of macros below to enable vector division:
153
130
* ```LIBDIVIDE_AVX512```
154
131
* ```LIBDIVIDE_NEON```
155
132
156
-
# Performance tips
133
+
## Performance Tips
157
134
158
135
* If possible use unsigned integer types because libdivide's unsigned division is measurably
159
136
faster than its signed division. This is especially true for the branchfree divider.
@@ -165,34 +142,23 @@ Note that you need to define one of macros below to enable vector division:
165
142
currently no vector multiplication instructions on x86 to efficiently calculate
166
143
64-bit * 64-bit to 128-bit.
167
144
168
-
# Build instructions
145
+
## Build instructions
169
146
170
-
libdivide has one test program and two benchmark programs which can be built using cmake and
171
-
a recent C++ compiler that supports C++11 or later. Optionally ```libdivide.h``` can also be
172
-
installed to ```/usr/local/include```.
147
+
libdivide has one test program and two benchmark programs which can be built using cmake and a recent C++ compiler that supports C++11 or later. Optionally ```libdivide.h``` can also be installed to ```/usr/local/include```.
173
148
174
149
```bash
175
150
cmake .
176
151
make -j
177
152
sudo make install
178
153
```
179
154
180
-
# Tester program
155
+
##Tester program
181
156
182
-
You can pass the **tester** program one or more of the following arguments: ```u32```,
183
-
```s32```, ```u64```, ```s64``` to test the four cases (signed, unsigned, 32-bit, or 64-bit), or
184
-
run it with no arguments to test all four. The tester will verify the correctness of libdivide
185
-
via a set of randomly chosen numerators and denominators, by comparing the result of libdivide's
186
-
division to hardware division. It will stop with an error message as soon as it finds a
187
-
discrepancy.
157
+
You can pass the **tester** program one or more of the following arguments: ```u32```, ```s32```, ```u64```, ```s64``` to test the four cases (signed, unsigned, 32-bit, or 64-bit), or run it with no arguments to test all four. The tester will verify the correctness of libdivide via a set of randomly chosen numerators and denominators, by comparing the result of libdivide's division to hardware division. It will stop with an error message as soon as it finds a discrepancy.
188
158
189
-
# Benchmark program
159
+
##Benchmark program
190
160
191
-
You can pass the **benchmark** program one or more of the following arguments: ```u16```, ```s16```, ```u32```,
192
-
```s32```, ```u64```, ```s64``` to compare libdivide's speed against hardware division.
193
-
**benchmark** tests a simple function that inputs an array of random numerators and a single
194
-
divisor, and returns the sum of their quotients. It tests this using both hardware division, and
195
-
the various division approaches supported by libdivide, including vector division.
161
+
You can pass the **benchmark** program one or more of the following arguments: ```u16```, ```s16```, ```u32```, ```s32```, ```u64```, ```s64``` to compare libdivide's speed against hardware division. **benchmark** tests a simple function that inputs an array of random numerators and a single divisor, and returns the sum of their quotients. It tests this using both hardware division, and the various division approaches supported by libdivide, including vector division.
196
162
197
163
It will output data like this:
198
164
@@ -207,9 +173,7 @@ It will output data like this:
207
173
...
208
174
```
209
175
210
-
It will keep going as long as you let it, so it's best to stop it when you are happy with the
211
-
denominators tested. These columns have the following significance. All times are in
212
-
nanoseconds, lower is better.
176
+
It will keep going as long as you let it, so it's best to stop it when you are happy with the denominators tested. These columns have the following significance. All times are in nanoseconds, lower is better.
213
177
214
178
```
215
179
#: The divisor that is tested
@@ -222,10 +186,9 @@ vec_bf: libdivide time, using vector branchfree division
222
186
algo: The algorithm used.
223
187
```
224
188
225
-
The **benchmark** program will also verify that each function returns the same value,
226
-
so benchmark is valuable for its verification as well.
189
+
The **benchmark** program will also verify that each function returns the same value, so benchmark is valuable for its verification as well.
227
190
228
-
# Contributing
191
+
##Contributing
229
192
230
193
Although there are no individual unit tests, the supplied ```cmake``` builds do include several safety nets:
1. Manually run the [Create draft release](https://github.com/ridiculousfish/libdivide/actions/workflows/prepare_release.yml) workflow/action.
6
+
* Choose the branch to release from (usually ```master```) and the release type (based on [Semantic Versioning](https://semver.org/))
7
+
* The action will do some codebase housekeeping and create a draft release:
8
+
* Creates a new commit with updated version numbers in ```libdivide.h```, ```CMakeLists.txt```, ```library.properties```.
9
+
* Creates a draft Git tag of format vX.Y.Z.
10
+
2. Once the action is complete, follow the output link in the action summary to the generated draft release. E.g. 
11
+
3. Edit the generated release notes as needed & publish
12
+
13
+
Note that PRs with the ```ignore-for-release``` label are excluded from the generated release notes.
0 commit comments