From 4ce82e695c10ddad57215bdbeafb68b8c5df2c30 Mon Sep 17 00:00:00 2001 From: Martin Holst Swende Date: Tue, 9 Jun 2020 11:22:06 +0200 Subject: [PATCH] update readme (#78) --- README.md | 205 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 105 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 8e7706bb..d75f99c2 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Fixed size 256-bit math library -This is a library specialized at replacing the big.Int library for math based on 256-bit types. This is meant for use in [go-ethereum](https://github.com/ethereum/go-ethereum) eventually, once it's deemed fast, stable and secure enough. +This is a library specialized at replacing the big.Int library for math based on 256-bit types, used by both +[go-ethereum](https://github.com/ethereum/go-ethereum) and [turbo-geth](https://github.com/ledgerwatch/turbo-geth). ## Benchmarks @@ -12,132 +13,136 @@ Current benchmarks, with tests ending with `big` being the standard `big.Int` li - And as of release `0.1.0`, the `uint256` library is alloc-free. - With the `1.0.0` release, it also has `100%` test coverage. -### Conversion from/to `big.Int` +### Conversion from/to `big.Int` and other formats ``` -BenchmarkSetFromBig/1word-6 252819142 5.02 ns/op 0 B/op 0 allocs/op -BenchmarkSetFromBig/2words-6 246641738 5.17 ns/op 0 B/op 0 allocs/op -BenchmarkSetFromBig/3words-6 238986948 5.11 ns/op 0 B/op 0 allocs/op -BenchmarkSetFromBig/4words-6 235735474 5.29 ns/op 0 B/op 0 allocs/op -BenchmarkSetFromBig/overflow-6 233997644 5.76 ns/op 0 B/op 0 allocs/op -BenchmarkToBig/1word-6 16905244 76.4 ns/op 64 B/op 2 allocs/op -BenchmarkToBig/2words-6 16532232 75.3 ns/op 64 B/op 2 allocs/op -BenchmarkToBig/3words-6 16193755 73.7 ns/op 64 B/op 2 allocs/op -BenchmarkToBig/4words-6 16226127 76.5 ns/op 64 B/op 2 allocs/op +BenchmarkSetFromBig/1word-6 253798280 4.84 ns/op 0 B/op 0 allocs/op +BenchmarkSetFromBig/2words-6 242738034 5.00 ns/op 0 B/op 0 allocs/op +BenchmarkSetFromBig/3words-6 233704105 5.22 ns/op 0 B/op 0 allocs/op +BenchmarkSetFromBig/4words-6 192542544 5.70 ns/op 0 B/op 0 allocs/op +BenchmarkSetFromBig/overflow-6 212680123 6.05 ns/op 0 B/op 0 allocs/op +BenchmarkToBig/1word-6 14953528 81.6 ns/op 64 B/op 2 allocs/op +BenchmarkToBig/2words-6 15932970 85.1 ns/op 64 B/op 2 allocs/op +BenchmarkToBig/3words-6 15629001 77.0 ns/op 64 B/op 2 allocs/op +BenchmarkToBig/4words-6 14525355 78.0 ns/op 64 B/op 2 allocs/op +BenchmarkSetBytes/generic-6 5386718 230 ns/op 0 B/op 0 allocs/op +BenchmarkSetBytes/specific-6 9418405 130 ns/op 0 B/op 0 allocs/op +BenchmarkRLPEncoding-6 82531 13085 ns/op 11911 B/op 255 allocs/op + ``` ### Math operations `uint256`: ``` -Benchmark_Add/single/uint256-6 629591630 1.93 ns/op 0 B/op 0 allocs/op -Benchmark_Sub/single/uint256-6 546594793 2.19 ns/op 0 B/op 0 allocs/op -Benchmark_Sub/single/uint256_of-6 569249097 2.12 ns/op 0 B/op 0 allocs/op -BenchmarkMul/single/uint256-6 121926037 8.92 ns/op 0 B/op 0 allocs/op -BenchmarkSquare/single/uint256-6 175970640 6.86 ns/op 0 B/op 0 allocs/op -Benchmark_Exp/large/uint256-6 325039 3698 ns/op 0 B/op 0 allocs/op -Benchmark_Exp/small/uint256-6 3832027 328 ns/op 0 B/op 0 allocs/op -BenchmarkDiv/small/uint256-6 86487969 14.3 ns/op 0 B/op 0 allocs/op -BenchmarkDiv/mod64/uint256-6 18414321 66.7 ns/op 0 B/op 0 allocs/op -BenchmarkDiv/mod128/uint256-6 9474686 120 ns/op 0 B/op 0 allocs/op -BenchmarkDiv/mod192/uint256-6 11031271 107 ns/op 0 B/op 0 allocs/op -BenchmarkDiv/mod256/uint256-6 13804608 87.3 ns/op 0 B/op 0 allocs/op -BenchmarkMod/small/uint256-6 83189749 14.3 ns/op 0 B/op 0 allocs/op -BenchmarkMod/mod64/uint256-6 17734662 67.8 ns/op 0 B/op 0 allocs/op -BenchmarkMod/mod128/uint256-6 10050982 119 ns/op 0 B/op 0 allocs/op -BenchmarkMod/mod192/uint256-6 10477886 112 ns/op 0 B/op 0 allocs/op -BenchmarkMod/mod256/uint256-6 13230618 92.0 ns/op 0 B/op 0 allocs/op -BenchmarkAddMod/small/uint256-6 64955443 19.5 ns/op 0 B/op 0 allocs/op -BenchmarkAddMod/mod64/uint256-6 15589430 79.0 ns/op 0 B/op 0 allocs/op -BenchmarkAddMod/mod128/uint256-6 8173804 138 ns/op 0 B/op 0 allocs/op -BenchmarkAddMod/mod192/uint256-6 9115947 133 ns/op 0 B/op 0 allocs/op -BenchmarkAddMod/mod256/uint256-6 10549335 119 ns/op 0 B/op 0 allocs/op -BenchmarkMulMod/small/uint256-6 29009958 41.4 ns/op 0 B/op 0 allocs/op -BenchmarkMulMod/mod64/uint256-6 10366879 115 ns/op 0 B/op 0 allocs/op -BenchmarkMulMod/mod128/uint256-6 5339348 256 ns/op 0 B/op 0 allocs/op -BenchmarkMulMod/mod192/uint256-6 5322434 231 ns/op 0 B/op 0 allocs/op -BenchmarkMulMod/mod256/uint256-6 5229891 229 ns/op 0 B/op 0 allocs/op -Benchmark_SDiv/large/uint256-6 10094680 122 ns/op 0 B/op 0 allocs/op +Benchmark_Add/single/uint256-6 575308741 2.19 ns/op 0 B/op 0 allocs/op +Benchmark_Sub/single/uint256-6 551694393 2.71 ns/op 0 B/op 0 allocs/op +Benchmark_Sub/single/uint256_of-6 405466652 2.52 ns/op 0 B/op 0 allocs/op +BenchmarkMul/single/uint256-6 147034321 8.19 ns/op 0 B/op 0 allocs/op +BenchmarkMulOverflow/single/uint256-6 45344761 25.4 ns/op 0 B/op 0 allocs/op +BenchmarkSquare/single/uint256-6 196272379 6.14 ns/op 0 B/op 0 allocs/op +Benchmark_Exp/large/uint256-6 374550 3199 ns/op 0 B/op 0 allocs/op +Benchmark_Exp/small/uint256-6 4426760 270 ns/op 0 B/op 0 allocs/op +BenchmarkDiv/small/uint256-6 94629267 12.5 ns/op 0 B/op 0 allocs/op +BenchmarkDiv/mod64/uint256-6 17367373 67.6 ns/op 0 B/op 0 allocs/op +BenchmarkDiv/mod128/uint256-6 10192484 130 ns/op 0 B/op 0 allocs/op +BenchmarkDiv/mod192/uint256-6 10936984 107 ns/op 0 B/op 0 allocs/op +BenchmarkDiv/mod256/uint256-6 13436908 93.5 ns/op 0 B/op 0 allocs/op +BenchmarkMod/small/uint256-6 80138805 15.2 ns/op 0 B/op 0 allocs/op +BenchmarkMod/mod64/uint256-6 17065768 72.1 ns/op 0 B/op 0 allocs/op +BenchmarkMod/mod128/uint256-6 9469146 123 ns/op 0 B/op 0 allocs/op +BenchmarkMod/mod192/uint256-6 11193145 115 ns/op 0 B/op 0 allocs/op +BenchmarkMod/mod256/uint256-6 12896706 93.1 ns/op 0 B/op 0 allocs/op +BenchmarkAddMod/small/uint256-6 62187169 21.0 ns/op 0 B/op 0 allocs/op +BenchmarkAddMod/mod64/uint256-6 15169026 82.5 ns/op 0 B/op 0 allocs/op +BenchmarkAddMod/mod128/uint256-6 8460835 144 ns/op 0 B/op 0 allocs/op +BenchmarkAddMod/mod192/uint256-6 9273334 141 ns/op 0 B/op 0 allocs/op +BenchmarkAddMod/mod256/uint256-6 10145329 113 ns/op 0 B/op 0 allocs/op +BenchmarkMulMod/small/uint256-6 26673195 42.3 ns/op 0 B/op 0 allocs/op +BenchmarkMulMod/mod64/uint256-6 10133446 125 ns/op 0 B/op 0 allocs/op +BenchmarkMulMod/mod128/uint256-6 4955551 229 ns/op 0 B/op 0 allocs/op +BenchmarkMulMod/mod192/uint256-6 5210977 220 ns/op 0 B/op 0 allocs/op +BenchmarkMulMod/mod256/uint256-6 5527972 220 ns/op 0 B/op 0 allocs/op +Benchmark_SDiv/large/uint256-6 9823093 124 ns/op 0 B/op 0 allocs/op ``` vs `big.Int` ``` -Benchmark_Add/single/big-6 48557786 21.9 ns/op 0 B/op 0 allocs/op -Benchmark_Sub/single/big-6 55511476 21.7 ns/op 0 B/op 0 allocs/op -BenchmarkMul/single/big-6 17177685 72.1 ns/op 0 B/op 0 allocs/op -BenchmarkSquare/single/big-6 18434874 67.6 ns/op 0 B/op 0 allocs/op -Benchmark_Exp/large/big-6 30236 34919 ns/op 18144 B/op 189 allocs/op -Benchmark_Exp/small/big-6 138970 8290 ns/op 7392 B/op 77 allocs/op -BenchmarkDiv/small/big-6 20982415 55.9 ns/op 8 B/op 1 allocs/op -BenchmarkDiv/mod64/big-6 7928998 168 ns/op 8 B/op 1 allocs/op -BenchmarkDiv/mod128/big-6 3858378 312 ns/op 80 B/op 1 allocs/op -BenchmarkDiv/mod192/big-6 4733641 251 ns/op 80 B/op 1 allocs/op -BenchmarkDiv/mod256/big-6 5928298 204 ns/op 80 B/op 1 allocs/op -BenchmarkMod/small/big-6 21673300 63.5 ns/op 8 B/op 1 allocs/op -BenchmarkMod/mod64/big-6 7451844 162 ns/op 64 B/op 1 allocs/op -BenchmarkMod/mod128/big-6 4138648 308 ns/op 64 B/op 1 allocs/op -BenchmarkMod/mod192/big-6 4895036 244 ns/op 48 B/op 1 allocs/op -BenchmarkMod/mod256/big-6 6530869 208 ns/op 8 B/op 1 allocs/op -BenchmarkAddMod/small/big-6 16872976 73.4 ns/op 8 B/op 1 allocs/op -BenchmarkAddMod/mod64/big-6 6000974 204 ns/op 77 B/op 1 allocs/op -BenchmarkAddMod/mod128/big-6 3480322 355 ns/op 64 B/op 1 allocs/op -BenchmarkAddMod/mod192/big-6 3627595 309 ns/op 61 B/op 1 allocs/op -BenchmarkAddMod/mod256/big-6 4768058 247 ns/op 40 B/op 1 allocs/op -BenchmarkMulMod/small/big-6 15861763 77.0 ns/op 8 B/op 1 allocs/op -BenchmarkMulMod/mod64/big-6 3656503 330 ns/op 96 B/op 1 allocs/op -BenchmarkMulMod/mod128/big-6 2104412 577 ns/op 96 B/op 1 allocs/op -BenchmarkMulMod/mod192/big-6 2198616 534 ns/op 80 B/op 1 allocs/op -BenchmarkMulMod/mod256/big-6 2492029 536 ns/op 80 B/op 1 allocs/op -Benchmark_SDiv/large/big-6 2056039 938 ns/op 312 B/op 6 allocs/op +Benchmark_Add/single/big-6 45798462 25.0 ns/op 0 B/op 0 allocs/op +Benchmark_Sub/single/big-6 51314886 23.7 ns/op 0 B/op 0 allocs/op +BenchmarkMul/single/big-6 14101502 75.9 ns/op 0 B/op 0 allocs/op +BenchmarkMulOverflow/single/big-6 15774238 81.5 ns/op 0 B/op 0 allocs/op +BenchmarkSquare/single/big-6 16739438 71.5 ns/op 0 B/op 0 allocs/op +Benchmark_Exp/large/big-6 41250 42132 ns/op 18144 B/op 189 allocs/op +Benchmark_Exp/small/big-6 130993 10813 ns/op 7392 B/op 77 allocs/op +BenchmarkDiv/small/big-6 18169453 70.8 ns/op 8 B/op 1 allocs/op +BenchmarkDiv/mod64/big-6 7500694 147 ns/op 8 B/op 1 allocs/op +BenchmarkDiv/mod128/big-6 3075676 370 ns/op 80 B/op 1 allocs/op +BenchmarkDiv/mod192/big-6 3908166 307 ns/op 80 B/op 1 allocs/op +BenchmarkDiv/mod256/big-6 4416366 252 ns/op 80 B/op 1 allocs/op +BenchmarkMod/small/big-6 19958649 70.8 ns/op 8 B/op 1 allocs/op +BenchmarkMod/mod64/big-6 6718828 167 ns/op 64 B/op 1 allocs/op +BenchmarkMod/mod128/big-6 3347608 349 ns/op 64 B/op 1 allocs/op +BenchmarkMod/mod192/big-6 4072453 293 ns/op 48 B/op 1 allocs/op +BenchmarkMod/mod256/big-6 4545860 254 ns/op 8 B/op 1 allocs/op +BenchmarkAddMod/small/big-6 13976365 79.6 ns/op 8 B/op 1 allocs/op +BenchmarkAddMod/mod64/big-6 5799034 208 ns/op 77 B/op 1 allocs/op +BenchmarkAddMod/mod128/big-6 2998821 409 ns/op 64 B/op 1 allocs/op +BenchmarkAddMod/mod192/big-6 3420640 351 ns/op 61 B/op 1 allocs/op +BenchmarkAddMod/mod256/big-6 4124067 298 ns/op 40 B/op 1 allocs/op +BenchmarkMulMod/small/big-6 14748193 85.8 ns/op 8 B/op 1 allocs/op +BenchmarkMulMod/mod64/big-6 3524833 420 ns/op 96 B/op 1 allocs/op +BenchmarkMulMod/mod128/big-6 1851936 637 ns/op 96 B/op 1 allocs/op +BenchmarkMulMod/mod192/big-6 2028134 584 ns/op 80 B/op 1 allocs/op +BenchmarkMulMod/mod256/big-6 2125716 576 ns/op 80 B/op 1 allocs/op +Benchmark_SDiv/large/big-6 1658139 848 ns/op 312 B/op 6 allocs/op ``` ### Boolean logic `uint256` ``` -Benchmark_And/single/uint256-6 590464702 1.93 ns/op 0 B/op 0 allocs/op -Benchmark_Or/single/uint256-6 629714779 2.06 ns/op 0 B/op 0 allocs/op -Benchmark_Xor/single/uint256-6 625039024 1.94 ns/op 0 B/op 0 allocs/op -Benchmark_Cmp/single/uint256-6 408978940 2.90 ns/op 0 B/op 0 allocs/op -BenchmarkLt/large/uint256-6 388216880 3.14 ns/op 0 B/op 0 allocs/op -BenchmarkLt/small/uint256-6 388475845 3.37 ns/op 0 B/op 0 allocs/op - +Benchmark_And/single/uint256-6 571318570 2.13 ns/op 0 B/op 0 allocs/op +Benchmark_Or/single/uint256-6 500672864 2.09 ns/op 0 B/op 0 allocs/op +Benchmark_Xor/single/uint256-6 575198724 2.24 ns/op 0 B/op 0 allocs/op +Benchmark_Cmp/single/uint256-6 400446943 3.09 ns/op 0 B/op 0 allocs/op +BenchmarkLt/large/uint256-6 322143085 3.50 ns/op 0 B/op 0 allocs/op +BenchmarkLt/small/uint256-6 351231680 3.33 ns/op 0 B/op 0 allocs/op ``` vs `big.Int` ``` -Benchmark_And/single/big-6 86528250 14.6 ns/op 0 B/op 0 allocs/op -Benchmark_Or/single/big-6 69813108 17.7 ns/op 0 B/op 0 allocs/op -Benchmark_Xor/single/big-6 66239239 18.2 ns/op 0 B/op 0 allocs/op -Benchmark_Cmp/single/big-6 160121772 7.46 ns/op 0 B/op 0 allocs/op -BenchmarkLt/large/big-6 84170188 12.5 ns/op 0 B/op 0 allocs/op -BenchmarkLt/small/big-6 84369852 13.2 ns/op 0 B/op 0 allocs/op - +Benchmark_And/single/big-6 78524395 16.2 ns/op 0 B/op 0 allocs/op +Benchmark_Or/single/big-6 65390958 20.5 ns/op 0 B/op 0 allocs/op +Benchmark_Xor/single/big-6 58333172 20.6 ns/op 0 B/op 0 allocs/op +Benchmark_Cmp/single/big-6 144781878 8.37 ns/op 0 B/op 0 allocs/op +BenchmarkLt/large/big-6 95643212 13.8 ns/op 0 B/op 0 allocs/op +BenchmarkLt/small/big-6 84561792 14.6 ns/op 0 B/op 0 allocs/op ``` ### Bitwise shifts `uint256`: ``` -Benchmark_Lsh/n_eq_0/uint256-6 260736044 4.61 ns/op 0 B/op 0 allocs/op -Benchmark_Lsh/n_gt_192/uint256-6 208642209 6.60 ns/op 0 B/op 0 allocs/op -Benchmark_Lsh/n_gt_128/uint256-6 185939301 6.29 ns/op 0 B/op 0 allocs/op -Benchmark_Lsh/n_gt_64/uint256-6 134935269 8.84 ns/op 0 B/op 0 allocs/op -Benchmark_Lsh/n_gt_0/uint256-6 100000000 10.6 ns/op 0 B/op 0 allocs/op -Benchmark_Rsh/n_eq_0/uint256-6 267984342 4.47 ns/op 0 B/op 0 allocs/op -Benchmark_Rsh/n_gt_192/uint256-6 226595919 5.46 ns/op 0 B/op 0 allocs/op -Benchmark_Rsh/n_gt_128/uint256-6 174888495 7.03 ns/op 0 B/op 0 allocs/op -Benchmark_Rsh/n_gt_64/uint256-6 135138018 9.03 ns/op 0 B/op 0 allocs/op -Benchmark_Rsh/n_gt_0/uint256-6 100000000 10.8 ns/op 0 B/op 0 allocs/op +Benchmark_Lsh/n_eq_0/uint256-6 291558974 3.96 ns/op 0 B/op 0 allocs/op +Benchmark_Lsh/n_gt_192/uint256-6 208429646 5.80 ns/op 0 B/op 0 allocs/op +Benchmark_Lsh/n_gt_128/uint256-6 151857447 6.90 ns/op 0 B/op 0 allocs/op +Benchmark_Lsh/n_gt_64/uint256-6 124543732 9.55 ns/op 0 B/op 0 allocs/op +Benchmark_Lsh/n_gt_0/uint256-6 100000000 11.2 ns/op 0 B/op 0 allocs/op +Benchmark_Rsh/n_eq_0/uint256-6 296913555 4.08 ns/op 0 B/op 0 allocs/op +Benchmark_Rsh/n_gt_192/uint256-6 212698939 5.52 ns/op 0 B/op 0 allocs/op +Benchmark_Rsh/n_gt_128/uint256-6 157391629 7.59 ns/op 0 B/op 0 allocs/op +Benchmark_Rsh/n_gt_64/uint256-6 124916373 9.46 ns/op 0 B/op 0 allocs/op +Benchmark_Rsh/n_gt_0/uint256-6 100000000 11.5 ns/op ``` vs `big.Int`: ``` -Benchmark_Lsh/n_eq_0/big-6 22462352 52.2 ns/op 64 B/op 1 allocs/op -Benchmark_Lsh/n_gt_192/big-6 18483247 69.3 ns/op 96 B/op 1 allocs/op -Benchmark_Lsh/n_gt_128/big-6 17845354 67.6 ns/op 96 B/op 1 allocs/op -Benchmark_Lsh/n_gt_64/big-6 19200085 66.7 ns/op 80 B/op 1 allocs/op -Benchmark_Lsh/n_gt_0/big-6 18988237 63.1 ns/op 80 B/op 1 allocs/op -Benchmark_Rsh/n_eq_0/big-6 22768628 54.5 ns/op 64 B/op 1 allocs/op -Benchmark_Rsh/n_gt_192/big-6 29468035 38.1 ns/op 8 B/op 1 allocs/op -Benchmark_Rsh/n_gt_128/big-6 23145200 54.2 ns/op 48 B/op 1 allocs/op -Benchmark_Rsh/n_gt_64/big-6 19201986 86.3 ns/op 64 B/op 1 allocs/op -Benchmark_Rsh/n_gt_0/big-6 20327937 62.3 ns/op 64 B/op 1 allocs/op +Benchmark_Lsh/n_eq_0/big-6 21387698 78.6 ns/op 64 B/op 1 allocs/op +Benchmark_Lsh/n_gt_192/big-6 15645853 73.9 ns/op 96 B/op 1 allocs/op +Benchmark_Lsh/n_gt_128/big-6 15954750 75.0 ns/op 96 B/op 1 allocs/op +Benchmark_Lsh/n_gt_64/big-6 16771413 81.3 ns/op 80 B/op 1 allocs/op +Benchmark_Lsh/n_gt_0/big-6 17118044 70.7 ns/op 80 B/op 1 allocs/op +Benchmark_Rsh/n_eq_0/big-6 21585044 65.5 ns/op 64 B/op 1 allocs/op +Benchmark_Rsh/n_gt_192/big-6 28313300 42.3 ns/op 8 B/op 1 allocs/op +Benchmark_Rsh/n_gt_128/big-6 21191526 58.1 ns/op 48 B/op 1 allocs/op +Benchmark_Rsh/n_gt_64/big-6 15906076 69.0 ns/op 64 B/op 1 allocs/op +Benchmark_Rsh/n_gt_0/big-6 19234408 93.0 ns/op 64 B/op 1 allocs/op ``` ## Helping out