clojure.core.rrb-vector.debug — org.clojure/core.rrb-vector 0.2.0

all-vector-tree-nodes clj/s

(all-vector-tree-nodes v)

basic-node-errors clj/s

(basic-node-errors v)

check-catvec clj/s

(check-catvec extra-checks? & counts)

Perform a sequence of calls to catvec or checking-catvec on one or more core.rrb-vector vectors. Return true if Clojure's built-in concat function give the same results, otherwise false. Intended for use in tests of this library.

check-subvec clj/s

(check-subvec extra-checks? init & starts-and-ends)

Perform a sequence of calls to subvec an a core.rrb-vector vector, as well as a normal Clojure vector, returning true if they give the same results, otherwise false. Intended for use in tests of this library.

checking-catvec clj/s

(checking-catvec & args)

checking-catvec is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

Note that (get @d/debug-otps :catvec) is used to control tracing, validating, and return value sanity checks for checking-catvec as a whole. This includes controlling those options for the function checking-splice-rrbts, which is used to concatenate pairs of vectors when you call checking-catvec with 3 or more vectors. This takes a bit longer to do the checking on every concatenation, but catches problems closer to the time they are introduced.

opts map: (get @d/debug-opts :catvec)
function called if (:validating opts) is logical true:
    validating-catvec

checking-catvec-impl clj/s

(checking-catvec-impl)

(checking-catvec-impl v1)

(checking-catvec-impl v1 v2)

(checking-catvec-impl v1 v2 v3)

(checking-catvec-impl v1 v2 v3 v4)

(checking-catvec-impl v1 v2 v3 v4 & vn)

checking-catvec-impl is identical to catvec, except that it calls checking-splicev instead of splicev, for configurable additional checking on each call to checking-splicev.

checking-pop clj/s

(checking-pop coll)

These two namespace aliases will be used later in this documentation:

(require '[clojure.core.rrb-vector.debug :as d])
(require '[clojure.core.rrb-vector.debug-platform-dependent :as pd])

checking-pop passes its argument to clojure.core/pop, and if it returns, it returns whatever clojure.core/pop does. If checking-pop detects any problems, it will record information about the problems found in one or both of the global atoms 'd/failure-data' and 'd/warning-data', and optionally throw an exception.

If coll is not a vector type according to pd/is-vector?, then checking-pop simply behaves exactly like clojure.core/pop, with no additional checks performed. All of checking-pop's extra checks are specific to vectors.

If coll is a vector, then checking-pop looks up the key :pop in a global atom 'd/debug-opts'. The result of that lookup is a map we will call 'opts' below.

opts map: (get @d/debug-opts :pop)
function called if (:validating opts) is logical true:
    validating-pop

If (:trace opts) is true, then a debug trace message is printed to out.

If (:validate opts) is true, then validating-pop is called, using clojure.core/pop to do the real work, but validating-pop will check whether the return value looks correct relative to the input parameter value, i.e. it is equal to a sequence of values containing all but the last element of the input coll's sequence of values. See validating-pop documentation for additional details. This step records details of problems found in the atoms d/failure-data.

(:return-value-checks opts) should be a sequence of functions that each take the vector returned from calling clojure.core/pop, and return data about any errors or warnings they find in the internals of the vector data structure. Errors or warnings are appended to atoms d/failure-data and/or d/warning-data.

If either the validate or return value checks steps find an error, they throw an exception if (:continue-on-error opts) is logical false.

If the return value checks step finds no error, but does find a warning, it throws an exception if (:continue-on-warning opts) is logical false.

checking-pop! clj/s

(checking-pop! coll)

checking-pop! is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

opts map: (get @d/debug-opts :pop!)
function called if (:validating opts) is logical true:
    validating-pop!

checking-slicev clj/s

(checking-slicev & args)

checking-slicev is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

Unlike checking-pop, it seems unlikely that a user of core.rrb-vector would want to call this function directly. See checking-subvec. checking-slicev is part of the implementation of checking-subvec.

opts map: (get @d/debug-opts :subvec)  ;; _not_ :slicev
function called if (:validating opts) is logical true:
    validating-slicev

checking-splice-rrbts clj/s

(checking-splice-rrbts & args)

checking-splice-rrbts is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

Unlike checking-pop, it seems unlikely that a user of core.rrb-vector would want to call this function directly. See checking-catvec. checking-splice-rrbts is part of the implementation of checking-catvec.

opts map: (get @d/debug-opts :catvec)  ;; _not_ :splice-rrbts
function called if (:validating opts) is logical true:
    validating-splice-rrbts

checking-splice-rrbts-main clj/s

(checking-splice-rrbts-main & args)

checking-splice-rrbts-main is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

Unlike checking-pop, it seems unlikely that a user of core.rrb-vector would want to call this function directly. See checking-catvec. checking-splice-rrbts-main is part of the implementation of checking-catvec.

opts map: (get @d/debug-opts :catvec)  ;; _not_ :splice-rrbts-main
function called if (:validating opts) is logical true:
    validating-splice-rrbts-main

checking-splicev clj/s

(checking-splicev v1 v2)

checking-splicev is identical to splicev, except that it calls checking-splice-rrbts instead of splice-rrbts, for configurable additional checking on each call to checking-splice-rrbts.

It is more likely that a core.rrb-vector library user will want to call checking-catvec rather than this one. checking-splicev is part of the implementation of checking-catvec.

checking-subvec clj/s

(checking-subvec v start)

(checking-subvec v start end)

checking-subvec is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

opts map: (get @d/debug-opts :subvec)
function called if (:validating opts) is logical true:
    validating-slicev

checking-transient clj/s

(checking-transient coll)

checking-transient is similar to checking-pop, with the differences summarized below. See checking-pop documentation for details.

opts map: (get @d/debug-opts :transient)
function called if (:validating opts) is logical true:
    validating-transient

children-summary clj/s

(children-summary node shift get-array get-ranges regular? opts)

clear-failure-data! clj/s

(clear-failure-data!)

copying-seq clj/s

(copying-seq v)

cvec clj/s

(cvec coll)

dbg-vec clj/s

(dbg-vec v)

(dbg-vec v opts)

debug-opts clj/s

edit-nodes-errors clj/s

(edit-nodes-errors v)

failure-data clj/s

filter-indexes clj/s

(filter-indexes pred coll)

Return a sequence of all indexes of elements e of coll for which (pred e) returns logical true. 0 is the index of the first element.

first-diff clj/s

(first-diff xs ys)

Compare two sequences to see if they have = elements in the same order, and both sequences have the same number of elements. If all of those conditions are true, and no exceptions occur while calling seq, first, and next on the seqs of xs and ys, then return -1.

If two elements at the same index in each sequence are found not = to each other, or the sequences differ in their number of elements, return the index, 0 or larger, at which the first difference occurs.

If an exception occurs while calling seq, first, or next, throw an exception that contains the index at which this exception occurred.

fraction-full clj/s

(fraction-full v)

full-debug-opts clj/s

generative-check-catvec clj/s

(generative-check-catvec extra-checks? iterations max-vcnt min-cnt max-cnt)

Perform many calls to check-catvec with randomly generated inputs. Intended for use in tests of this library. Returns true if all tests pass, otherwise throws an exception containing data about the inputs that caused the failing test.

generative-check-subvec clj/s

(generative-check-subvec extra-checks? iterations max-init-cnt slices)

Perform many calls to check-subvec with randomly generated inputs. Intended for use in tests of this library. Returns true if all tests pass, otherwise throws an exception containing data about the inputs that caused the failing test.

leaves-with-internal-node-type clj/s

(leaves-with-internal-node-type node-infos)

max-capacity-divided-by-1024 clj/s

(max-capacity-divided-by-1024 root-shift)

non-leaves-not-internal-node-type clj/s

(non-leaves-not-internal-node-type node-infos)

non-regular-node-errors clj/s

(non-regular-node-errors node get-ranges children)

objects-in-slot-32-of-obj-arrays clj/s

(objects-in-slot-32-of-obj-arrays v)

Function to look for errors of the form where a node's node.array object, which is often an array of 32 or 33 java.lang.Object's, has an element at index 32 that is not nil, and refers to an object that is of any type except an array of ints. There appears to be some situation in which this can occur, but it seems to almost certainly be a bug if that happens, and we should be able to detect it whenever it occurs.

ranges-errors clj/s

(ranges-errors v)

record-failure-data clj/s

(record-failure-data d)

record-warning-data clj/s

(record-warning-data d)

regular-node-errors clj/s

(regular-node-errors root-node? root-node-cnt children)

sanity-check-vector-internals clj/s

(sanity-check-vector-internals err-desc-str ret args opts)

This function is called by all of the checking-* variants of functions in the debug namespace. It calls all of the functions in (:return-value-checks opts) in the order given, passing each of those functions a return value 'ret'. Each function performs sanity checks on the 'ret' data structure used to represent the vector.

Those functions should return a map with key :error having a logical true value if any errors were found, or a key :warning having a logical true value if any warnings were found, otherwise both of those values must be logical false in the returned map (or no such key is present in the returned map at all).

Three examples of such functions are included in core.rrb-vector's debug namespace.

• edit-nodes-errors
• basic-node-errors
• ranges-errors

They each look for different problems in the vector data structure internals. They were developed as separate functions in case there was ever a significant performance advantage to configuring only some of them to be called, not all of them, for long tests.

If any errors are found, this function calls record-failure-data, to record the details in a global atom. It prints a message to out, and if (:continue-on-error opts) is logical false, it throws a data conveying exception using ex-info containing the same message, and the same error details map passed to record-failure-data.

If no exception is thrown due to an error, then repeat the same checks for a warning message, recording details via calling record-warning-data, and throwing an exception if (:continue-on-warning opts) is logical false.

set-debug-opts! clj/s

(set-debug-opts! opts)

set-debug-opts! modified the debug-opts atom of the core.rrb-vector library, which configures what kinds of extra checks are performed when calling the checking-* versions of functions defined in the library's debug namespace.

Example call:

(require '[clojure.core.rrb-vector.debug :as d]) (d/set-debug-opts! d/full-debug-opts)

This call enables as thorough of extra verification checks as is supported by existing code, when you call any of the checking-* variants of the functions in this namespace, e.g. checking-catvec, checking-subvec.

It will also slow down your code to do so. checking-* functions return the same values as their non checking-* original functions they are based upon, so you can write application code that mixes calls to both, calling the checking-* versions only occasionally, if you have a long sequence of operations that you want to look for bugs within core.rrb-vector's implementation of.

slow-into clj/s

(slow-into to from)

validating-catvec clj/s

(validating-catvec err-desc-str & vs)

validating-catvec behaves similarly to validating-pop, but note that it does not allow you to pass in a function f on which to concatenate its arguments. It hardcodes d/checking-catvec-impl for that purpose. See validating-pop for more details.

opts map: (get @d/debug-opts :catvec)

If no exception is thrown, the return value is (apply checking-catvec-impl vs).

validating-pop clj/s

(validating-pop f err-desc-str coll)

validating-pop is not really designed to be called from user programs. checking-pop can do everything that validating-pop can, and more. See its documentation.

A typical way of calling validating-pop is:

(require '[clojure.core.rrb-vector.debug :as d])
(d/validating-pop clojure.core/pop "pop" coll)

Most of the validating-* functions behave similarly. This one contains the most complete documentation, and the others refer to this one. They all differ in the function that they are intended to validate, and a few other details, which will be collected in one place here for function validating-pop so one can quickly see the differences between validating-pop and the other validating-* functions.

good example f: clojure.core/pop
opts map: (get @d/debug-opts :pop)

The first argument can be any function f. f is expected to take arguments and return a value equal to what clojure.core/pop would, given the argument coll.

validating-pop will first make a copy of the seq of items in coll, as a safety precaution, because some kinds of incorrect implementations of pop could mutate their input argument. That would be a bug, of course, but aiding a developer in detecting bugs is the reason validating-pop exists. It uses the function copying-seq to do this, which takes at least linear time in the size of coll.

It will then calculate a sequence that is = to the expected return value, e.g. for pop, all items in coll except the last one.

Then validating-pop will call (f coll), then call copying-seq on the return value.

If the expected and returned sequences are not =, then a map containing details about the arguments and actual return value is created and passed to d/record-failure-data, which appends the map to the end of a vector that is the value of an atom named d/failure-data. An exception is thrown if (:continue-on-error opts) is logical false, with ex-data equal to this same map of error data.

If the expected and actual sequences are the same, no state is modified and no exception is thrown.

If validating-pop does not throw an exception, the return value is (f coll).

validating-pop! clj/s

(validating-pop! f err-desc-str coll)

validating-pop! behaves the same as validating-pop, with the differences described here. See validating-pop for details.

good example f: clojure.core/pop!
opts map: (get @d/debug-opts :pop!)

If no exception is thrown, the return value is (f coll).

validating-slicev clj/s

(validating-slicev err-desc-str coll start)

(validating-slicev err-desc-str coll start end)

validating-slicev behaves similarly to validating-pop, but note that it does not allow you to pass in a function f to call. It hardcodes slicev for that purpose. See validating-pop for more details.

opts map: (get @d/debug-opts :subvec)  ;; _not_ :slicev

validating-splice-rrbts-main clj/s≠

clj

(validating-splice-rrbts-main err-desc-str nm am v1 v2)

cljs

(validating-splice-rrbts-main err-desc-str v1 v2)

validating-splice-rrbts-main behaves the same as validating-pop, with the differences described here. See validating-pop for details.

good example f: clojure.core.rrb-vector.rrbt/splice-rrbts-main
opts map: (get @d/debug-opts :catvec)  ;; _not_ :splice-rrbts-main

Given that splice-rrbts-main is an internal implementation detail of the core.rrb-vector library, it is expected that it is more likely you would call validating-catvec instead of this function.

If no exception is thrown, the return value is (f v1 v2).

validating-transient clj/s

(validating-transient f err-desc-str coll)

validating-transient behaves the same as validating-pop, with the differences described here. See validating-pop for details.

good example f: clojure.core/transient
opts map: (get @d/debug-opts :transient)

If no exception is thrown, the return value is (f coll).

validation-failure clj/s

(validation-failure err-msg-str failure-data opts)

warning-data clj/s