1 ! Copyright (C) 2018 Alexander Ilin.
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: checksums checksums.common checksums.md5 checksums.sha
4 destructors help.markup help.syntax kernel sequences ;
7 ABOUT: "checksums.multi"
9 ARTICLE: "checksums.multi" "Checksumming with Multiple Algorithms"
10 "The " { $vocab-link "checksums.multi" } " vocabulary makes it possible to calculate multiple checksums with just one pass over a data stream."
12 "The " { $link multi-checksum } " tuple holds a sequence of " { $link block-checksum } " instances, such as " { $link md5 } " or " { $link sha1 } ". When the " { $link initialize-checksum-state } " method is called on it, a new instance of " { $link block-checksum-state } " is created for all the " { $slot "checksums" } ", and returned as a new " { $link multi-state } " instance. You can then use " { $link add-checksum-bytes } " to stream data to it. When done, call " { $link get-checksum } " to finalize the process, read the resulting checksums and dispose of the tuple in one step. If you want to cancel the work without calling " { $link get-checksum } ", you must " { $link dispose } " of the tuple so that all implementation-specific resources are released."
14 "The " { $link checksum-bytes } " and the " { $link checksum-stream } " methods encapsulate the above protocol, including instantiation and disposal of the " { $link multi-state } " tuple."
16 { $unchecked-example "USING: byte-arrays checksums checksums.md5 checksums.sha ;"
17 "\"test\" >byte-array { md5 sha1 } <multi-checksum> checksum-bytes ."
20 9 143 107 205 70 33 211 115 202 222 78 131 38 39 180 246
23 169 74 143 229 204 177 155 166 28 76 8 115 211 145 233
28 { $unchecked-example "USING: checksums checksums.common checksums.md5 checksums.sha"
29 "io io.encodings.binary namespaces ;"
30 "\"LICENSE.txt\" binary ["
31 " input-stream get { md5 sha1 } <multi-checksum> checksum-stream"
32 "] with-file-reader ."
35 220 158 207 218 50 163 198 36 234 90 122 65 197 14 224
39 132 132 148 224 101 202 198 114 38 53 127 18 70 170 108
46 HELP: <multi-checksum>
48 { "checksums" sequence }
49 { "multi-checksum" multi-checksum }
51 { $description "This is a simple constructor for the " { $link multi-checksum } " tuple. The " { $snippet "checksums" } " must be a sequence of " { $link block-checksum } " instances." } ;
54 { $class-description "This is an instance of the " { $link block-checksum } " mixin. It calculates multiple checksums by sequentially passing the data it receives to all the checksums in its " { $slot "checksums" } " slot. This way, even though the individual checksums are not calculated in parallel, you still can have the performance benefits of only reading a disk file once, or not having to temporarily store the data streamed from a network." } ;
57 { $class-description "This class represents the current state of a " { $link multi-checksum } " checksum calculation. It has an array of associated checksum states until it is disposed. You may call " { $link add-checksum-bytes } " multiple times to pipe data to all the checksum states in the " { $slot "states" } " slot. When finished, call " { $link get-checksum } " to receive the results and release implementation-specific resources, or " { $link dispose } " to release the resources and discard the result. After the first " { $link get-checksum } " call the returned value is stored in the " { $slot "results" } " slot, and subsequent calls return the same value." }
58 { $notes "It is not possible to add more data to the checksum after the first " { $link get-checksum } " call."
60 "Most code should use " { $link with-checksum-state } " to make sure the resources are properly disposed of. Higher level words like " { $link checksum-bytes } " and " { $link checksum-stream } " use it to perform the disposal." } ;
62 { multi-checksum multi-state } related-words