Provides the raw interface for communicating with Hegel-core.
Provides the raw interface for communicating with Hegel-core.
This dynamic variable is bound to true when we're executing a final test case.
This dynamic variable is bound to true when we're executing a final test case.
(alive? core)Do we think this core is alive and well?
Do we think this core is alive and well?
(buf->raw-packet buf)Converts a ByteBuffer into a RawPacket, verifying the checksum.
Converts a ByteBuffer into a RawPacket, verifying the checksum.
(cbor-read-string b)Reads a string, whose payload is UTF-8, but with surrogate code points allowed.
Reads a string, whose payload is UTF-8, but with surrogate code points allowed.
(checksum packet)Computes the CRC32 checksum of a ByteBuffer Packet. The protocol docs say this is 'crS32(packet)', but I can't figure out what that is. I assume it's a typo?
Computes the CRC32 checksum of a ByteBuffer Packet. The protocol docs say this is 'crS32(packet)', but I can't figure out what that is. I assume it's a typo?
(clj->hegel x)Converts an idiomatic Clojure data structure into a Hegel one. Turns keywords to strings, and kebab-case to snake_case. Only does this for map keys.
Converts an idiomatic Clojure data structure into a Hegel one. Turns keywords to strings, and kebab-case to snake_case. Only does this for map keys.
(close-stream! core stream-id)Closes a stream on the given core. Returns core.
Closes a stream on the given core. Returns core.
(collection-more? core stream-id collection-id)Asks core if we should produce another element for the given collection ID. Takes a Core, stream ID, and collection ID. Returns true iff we should generate another element.
Asks core if we should produce another element for the given collection ID. Takes a Core, stream ID, and collection ID. Returns true iff we should generate another element.
(collection-reject! core stream-id collection-id)Informs core that we didn't like the last element it generated for the given collection ID. Takes a Core, stream ID, and collection ID.
Informs core that we didn't like the last element it generated for the given collection ID. Takes a Core, stream ID, and collection ID.
How long do we wait for Hegel to respond to a command, in millis?
How long do we wait for Hegel to respond to a command, in millis?
The ID of the special control stream.
The ID of the special control stream.
The version of hegel-core we ask uv for.
The version of hegel-core we ask uv for.
What version string do we expect from Hegel-core? Weirdly this is not the same as the Hegel version.
What version string do we expect from Hegel-core? Weirdly this is *not* the same as the Hegel version.
(crash-core! core exception)Used when an error occurs. Stops core, then fills in every pending promise with the given exception.
Used when an error occurs. Stops core, then fills in every pending promise with the given exception.
(default m k v)Provides a default for a map.
Provides a default for a map.
(deref-rethrow derefable)(deref-rethrow derefable timeout-ms)Deref with unwrapping throw. It's sort of confusing and not really relevant that we construct HegelErrors in the reader thread, then hand them off through Futures; it complicates catch blocks and the cause stacktrace isn't actually that useful.
We extract HegelErrors from a thrown ExecutionException and throw a new HegelError from the current callsite.
Deref with unwrapping throw. It's sort of confusing and not really relevant that we construct HegelErrors in the reader thread, then hand them off through Futures; it complicates catch blocks and the cause stacktrace isn't actually that useful. We extract HegelErrors from a thrown ExecutionException and throw a *new* HegelError from the current callsite.
(error-type payload)Errors are maps with an 'error' key, which is a meaningless, unstable integer (!?), and a 'type' key (e.g. 'StopTest'), which is useful. Returns the type of an error as a qualified keyword ala ::hegel-clj/stop-test, else nil.
Errors are maps with an 'error' key, which is a meaningless, unstable integer (!?), and a 'type' key (e.g. 'StopTest'), which is useful. Returns the type of an error as a qualified keyword ala ::hegel-clj/stop-test, else nil.
(friendly-message-id id)It's a pain to try and do twos-complement bit arithmatic in one's head to map between request and reply IDs. This prints a friendly string for a message ID, either '123' for a request, or 'r123' for the corresponding reply.
It's a pain to try and do twos-complement bit arithmatic in one's head to map between request and reply IDs. This prints a friendly string for a message ID, either '123' for a request, or 'r123' for the corresponding reply.
(gen-coll-id! core)Generates a unique collection ID.
Generates a unique collection ID.
(gen-message-id! core stream-id)Generates a fresh message ID for the given stream.
Generates a fresh message ID for the given stream.
(gen-span-type! core)Generates a unique type for a span.
Generates a unique type for a span.
(generate! core stream-id schema)Asks a core to generate a value. Takes a Core, stream id, and a Schema from hegel-clj.gen.
Asks a core to generate a value. Takes a Core, stream id, and a Schema from hegel-clj.gen.
(handshake! core)Sends the handshake message and awaits the reply. Returns reply payload.
Sends the handshake message and awaits the reply. Returns reply payload.
(hegel->clj x)Converts a Hegel data structure into a Clojure one. Turns strings to keywords, and snake-_case to kebab-case. Only for map keys.
Converts a Hegel data structure into a Clojure one. Turns strings to keywords, and snake-_case to kebab-case. Only for map keys.
(->raw-packet p)Converts a Packet to a RawPacket.
Converts a Packet to a RawPacket.
(kebab-case-kw s)Converts underscored strings to kebab-case keywords.
Converts underscored strings to kebab-case keywords.
(maybe-finish-test! core
test-stream-id
final-countdown
final-case-results
tmp-results
results)Called when we might be done with a test. If the final countdown is zero, delivers the results of final-case-results and tmp-results to results, and closes the test stream.
Called when we might be done with a test. If the final countdown is zero, delivers the results of final-case-results and tmp-results to results, and closes the test stream.
(new-collection! core stream-id {:keys [min-size max-size]})Asks core to create a new collection. Takes a Core, a stream id, and options. Returns a collection id, which you should use to ask for more elements, or reject elements.
{:min-size 3
:max-size 6}
Asks core to create a new collection. Takes a Core, a stream id, and
options. Returns a collection id, which you should use to ask for more
elements, or reject elements.
{:min-size 3
:max-size 6}(next-message-id message-id)Picks the next message ID. Non-reply messages are always positive. Yes this is weird; I don't know why the spec uses the low bits for stream IDs and the high bits for message ID flags.
Picks the next message ID. Non-reply messages are always positive. Yes this is weird; I don't know why the spec uses the low bits for stream IDs and the high bits for message ID flags.
(next-stream-id stream-id)Picks the next stream ID. Client-created streams always have odd stream IDs.
Picks the next stream ID. Client-created streams always have odd stream IDs.
(on-test-done! core
test-stream-id
case-fn
final-countdown
final-case-results
tmp-results
results
req)Part of run-test!. Same arguments; this part handles a test_done command by transitioning to the final phase of the test.
Part of run-test!. Same arguments; this part handles a test_done command by transitioning to the final phase of the test.
(open-stream! core)(open-stream! core stream-id)Generates a fresh stream on the given core, returning its ID. If given an ID, prepares that stream for use locally.
Generates a fresh stream on the given core, returning its ID. If given an ID, prepares that stream for use locally.
(raw-packet->buf packet)Converts a RawPacket to a ByteBuffer.
Converts a RawPacket to a ByteBuffer.
(read-int! in buf)Reads an integer from an InputStream, using the given ByteBuffer as a scratchpad.
Reads an integer from an InputStream, using the given ByteBuffer as a scratchpad.
(read-loop! core)Reads packets from the inputstream, dispatching them. Takes a Core.
Reads packets from the inputstream, dispatching them. Takes a Core.
(read-terminator! in)Reads a single terminator byte, validating it.
Reads a single terminator byte, validating it.
(reader! core)Spawns a future for a core to read incoming messages.
Spawns a future for a core to read incoming messages.
(register-stream-handler! core stream-id handler)Registers a stream handler function for incoming Packets.
Registers a stream handler function for incoming Packets.
(reply! core req-packet res-body)Replies to a Packet with a CBOR body.
Replies to a Packet with a CBOR body.
(request-message-id reply-id)Computes the request message ID for a given reply message ID.
Computes the request message ID for a given reply message ID.
(response-message-id request-id)Computes the response message ID for a given request message ID.
Computes the response message ID for a given request message ID.
(rpc! core packet)Sends an RPC request, registering a Future which will receive the payload of the reply to this message.
Sends an RPC request, registering a Future which will receive the payload of the reply to this message.
(run-test! core opts case-fn)Sends a run-test command. Options are:
:test-cases The number of test cases to run (default 100)
:seed A random seed
:derandomize If true, and seed is not set, derives a determinstic
seed from database-key
:database-key A stable database key for this test
:database A path to the DB directory
:suppress-health-check A vector of health check keywords to suppress:
any of :test-cases-too-large, :filter-too-much,
:too-slow, :large-initial-test-case
Takes a function (case-fn) which will be invoked approximately test-cases
times, with zero arguments. This function can generate values and should
return a map which explains whether the case was valid or not:
{:status :valid}
{:status :invalid}
{:status :interesting
:origin "..."}
These maps can have extra information, which will be returned to you via
:final in the event Hegel finds interesting test cases. The :origin key
tells Hegel where the failure occurred; I suggest a file name and line
number. Origin is optional: if omitted, it will be the empty string.
Returns a map describing the results of the test, of the form:
:passed? Did all tests pass?)
:test-cases How many test cases were executed?
:valid-test-cases How many of them were valid
:invalid-test-cases How many of them were invalid
:interesting-test-cases How many of them were interesting (e.g. a bug)
:seed The random seed used
:flaky? Hegel thought this test was non-deterministic
:health-check-failure? Did a health check fail during the test?
:final A vector of result maps (e.g. {:status
:interesting, :origin "...", ...}) returned
from each test case run during the final phase.
May also throw an exception map like {:type :hegel-error, :message "..."}.
Sends a run-test command. Options are:
:test-cases The number of test cases to run (default 100)
:seed A random seed
:derandomize If true, and seed is not set, derives a determinstic
seed from database-key
:database-key A stable database key for this test
:database A path to the DB directory
:suppress-health-check A vector of health check keywords to suppress:
any of :test-cases-too-large, :filter-too-much,
:too-slow, :large-initial-test-case
Takes a function `(case-fn)` which will be invoked approximately `test-cases`
times, with zero arguments. This function can generate values and should
return a map which explains whether the case was valid or not:
{:status :valid}
{:status :invalid}
{:status :interesting
:origin "..."}
These maps can have extra information, which will be returned to you via
`:final` in the event Hegel finds interesting test cases. The `:origin` key
tells Hegel where the failure occurred; I suggest a file name and line
number. Origin is optional: if omitted, it will be the empty string.
Returns a map describing the results of the test, of the form:
:passed? Did all tests pass?)
:test-cases How many test cases were executed?
:valid-test-cases How many of them were valid
:invalid-test-cases How many of them were invalid
:interesting-test-cases How many of them were interesting (e.g. a bug)
:seed The random seed used
:flaky? Hegel thought this test was non-deterministic
:health-check-failure? Did a health check fail during the test?
:final A vector of result maps (e.g. {:status
:interesting, :origin "...", ...}) returned
from each test case run during the final phase.
May also throw an exception map like {:type :hegel-error, :message "..."}.(run-test-case! core
test-stream-id
case-fn
final-countdown
final-case-results
tmp-results
results
req)Part of run-test!. Same arguments; this part handles a test_case command from the server. Acknowledges the test-case command, invokes case-fn to perform the test case, and sends results back to the server.
Part of run-test!. Same arguments; this part handles a test_case command from the server. Acknowledges the test-case command, invokes case-fn to perform the test case, and sends results back to the server.
(run-test-handler! core
test-stream-id
case-fn
final-countdown
final-case-results
tmp-results
results
req)Handles messages received from the server during a test.
core The Hegel client core.
test-stream-id A stream ID for this test run
case-fn A function (case-fn stream-id) which runs a single test
case.
final-countdown An atom with the number of final test cases (those which
occur after the test_done message) we have yet to process.
tmp-results A promise where we store the result map during
the final test cases.
results A CompletableFuture which receives the result map once the
final test cases are complete. This is what the caller
blocks on.
req The request CborPacket we're processing.
Handles messages received from the server during a test.
`core` The Hegel client core.
`test-stream-id` A stream ID for this test run
`case-fn` A function (case-fn stream-id) which runs a single test
case.
`final-countdown` An atom with the number of final test cases (those which
occur after the test_done message) we have yet to process.
`tmp-results` A promise where we store the result map during
the final test cases.
`results` A CompletableFuture which receives the result map once the
final test cases are complete. This is what the caller
blocks on.
`req` The request CborPacket we're processing.(send! core packet)Sends an IPacket to Hegel core.
Sends an IPacket to Hegel core.
(snake-case-str s)Converts dashes in any named thing to underscored strings.
Converts dashes in any named thing to underscored strings.
(start-core!)Starts the Hegel daemon. Returns a Core record.
TODO: prefer HEGEL_SERVER_COMMAND
Starts the Hegel daemon. Returns a Core record. TODO: prefer HEGEL_SERVER_COMMAND
(start-span! core stream-id span-type)'Marks the start of a span of choices', says the docs. Takes a type integer, which should ideally be the same between two different runs of the same, uh... generator within a test. I don't fully understand this, but I know it helps with shrinking.
'Marks the start of a span of choices', says the docs. Takes a type integer, which should ideally be the same between two different runs of the same, uh... generator within a test. I don't fully understand this, but I know it helps with shrinking.
(stop-core! core)Stops the Hegel Core process.
Stops the Hegel Core process.
(stop-span! core stream-id)'Marks the end of a span of choices', says the docs.
'Marks the end of a span of choices', says the docs.
(update- m k f)(update- m k f a)(update- m k f a b)(update- m k f a b & cs)Like Clojure update, but only if the key exists.
Like Clojure update, but only if the key exists.
(vthread name & body)Runs body in a virtual thread under the given name.
Runs body in a virtual thread under the given name.
(with-core core-sym & body)Evaluates body with a Hegel core bound.
Evaluates body with a Hegel core bound.
(with-thread-name thread-name & body)Sets the thread name for duration of block.
Sets the thread name for duration of block.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |