use Sum::Recourse;

    # TODO sample code

role Sum::Recourse[ :recourse(:libmhash($x) :librhash($x) :libcrypto($x.lc) :Perl6($class)) ]

The Sum::Recourse role may be mixed in to allow runtime loading of native C implementations, fallback between native C implementations, and fallback to pure Perl 6 implementations of a given algorithm. The :recourse role parameter takes and ordered list of pairs. The key of each pair may be one of "libmhash", "librhash" or "libcrypto" to designate the use of a C implementation. Other such tags may be added in the future to serve other implementations. The value of each pair contains arguments to pass to the .new constructor for the corresponding native C class (e.g. the class Sum::libmhash::Sum in the case of "libmhash".) This will usually be the name of that algorithm in said library.

The special key "Perl6" designates a fallback to a pure Perl 6 implementation. The value of the key should be a fully composed Perl 6 class which has the necessary marshalling roles mixed in to behave similarly to classes such as Sum::libmash::Sum.

When a class including this role is instantiated, each of the pairs from :recourse will be considered in the order in which they appear. A check will be made to see if the specified native library is available, and if it is, an object from that library will be instantiated and method calls to certain methods will be forwarded to that object. If either the library is unavailable, or the object fails to instantiate, the next pair in the list will be tried until one succeeds, or until the end of the list is passed, in which case an X::Sum::Recourse Failure is returned instead.

Most of the ancillary roles from the Sum base interface may be mixed in alongside Sum::Recourse. Note that one must still mix in at least one Sum::Marshal::* role. Mixing in Sum::Partial will disable any librhash functionality even if it appears in :recourse, because librhash lacks the ability to clone contexts.

Note that most C implementations of hashing algorithms are not capable of generating checksums for messages that do not pack evenly into bytes, so one should not use Sum::Recourse for this purpose, and rather should construct a pure Perl 6 implementation from the roles provided in algorithm-specific modules if this functionality is needed.

method recourse(--> Str)

The .recourse method may be called on an instantiated object of the resulting class. It will return the textual key associated with the eventually chosen implementation.

role Sum::Recourse::Marshal

Most native implementations do not allow messages that do not pack evenly into bytes. For example, you cannot take the SHA1 of the 7-bit message 0101001 using libcrypto, librhash, or libmhash. In contrast the pure Perl 6 implementations do have this ability.

By default, we load native implementations, but if no C implementations are available on a system, a fallback to pure Perl 6 code is performed. When this happens it is important that the behavior of the class remains the same, so we cannot just directly use the Perl 6 implementation, as it handles addends differently.

The Sum::Recourse::Marshal role may be mixed in to most pure Perl 6 implementations to make it behave exactly like most native implementations (minus, of course, the speed.) When it is mixed in, one may directly .push a single blob8 no matter how many elements it has, pushing a 0-element blob8 is a no-op, even if the object is finalized, and processing for bitwise parameters and raw integers is not provided.

Note that you will not see Sum::Recourse::Marshal listed as a mixed in role for a class that does Sum::Recourse. This is because those classes are wrappers that just drive other class objects underneath. This allows a lot of extra Sum::Marshal:: classes to be mixed into the wrapper class and still work no matter which back-end is loaded at runtime.