A recipe with no environment, which is the usual kind.

Start a recipe on a payload, as a suspended computation for a driver to run with inspect. Pass an empty payload to start with no input. A failed value that the recipe didn't recover from is a ProtocolError.

Start a recipe on a payload. The result is Right if it finished within the payload, and otherwise Left with the suspended computation. This lets a loop handle the common case without a Stream.

runParser from a position in the payload, for a driver that reads one recipe after another from the same payload, as the connection reads rows, and handles a failed value itself. A recipe that finishes within the payload gives where it got to as a position in it, so the driver keeps the payload and a position rather than building the unread bytes after each recipe. A failed value that nothing recovered is FailedAt rather than a ProtocolError; a row's recipe (CompiledRow) leaves its failure for the driver this way. A recipe that suspends gives its failure as a Left at the end.

Run a recipe over payloads already in memory, followed by the end of the message. The result is the recipe's value and whatever input it didn't read.

Run a recipe to its end, starting with this payload and fetching the rest from the action. It also runs any consumers the recipe holds, with feedRunner for their pulls. The result includes the unread part of the last payload.

This is the driver to use unless you need something it doesn't do. A driver of your own must follow one rule: it must run each step of a suspended recipe only once. After inspect, save what inspect returned, and not the computation it was given, before anything can interrupt the driver. Running a step twice repeats its effects, and an Accumulator it holds would write into memory it may already have given away.

A recipe's result, and the part of the current payload it didn't read. The next recipe starts with those bytes.

Where a recipe that finished within its payload got to (runParserAt): its value, or the failed value (failValue) that nothing recovered, and in either case the position after it in the same payload.

What a suspended recipe asks its driver for. A suspended recipe is a Stream of these requests, so a driver sees three things as it runs one. Step is one of these requests, Effect is a short piece of IO that the driver just runs, such as growing a value's buffer, and Return is the final Got. Using inspect from the streaming package runs the effects and gives the next request or the result.

What a driver gives a suspended recipe: the next payload, with the transport and the TDS packet headers already removed, or the end of the message.

The payload, for a read that treats More and Discard alike, or Nothing at the end of the message.

How a streaming consumer gets the next piece of its value. consume gives the consumer a stream, and each pull from that stream calls the Runner.

The reference holds the suspended recipe that reads the value. runAwait runs that recipe until it produces its next result, fetching payloads whenever it needs them, and it saves its progress back in the reference as it goes, so that an interrupted pull doesn't repeat anything.

The driver supplies the Runner because only the driver knows where the payloads come from and what a pull must hold while it reads them. The connection's own Runner masks each pull and reads from that response's packets. feedRunner builds one from a function that returns the next payload.

A Runner that gets payloads from this action. Its caller decides what to mask and what to do about exceptions. It saves its progress before each step, so that retrying after a failed fetch, or looking again at a finished value, repeats nothing. A value's recipe that asks to run a consumer of its own is a ProtocolError, and it stays failed in the reference, so that later cleanup can't run the consumer.

Run a short piece of IO as part of a recipe, and evaluate its result. It runs once, under whatever mask the driver holds, so it must not block. Code that can block, such as a caller's consumer, belongs in consume instead.

Give a stream of bytes to a function that reads it as the bytes arrive, then carry on with the recipe. This is how a caller's code reads a large value without it being in memory (streamField is built on it). The result is what the function returned, or Nothing when the driver is throwing the response away and didn't run it. Whatever part of the stream the function didn't read is read past afterwards, so the recipe continues in the right place either way. An exception the function throws ends the driver instead (RunConsumer); the saved step then still holds the value, and a drain that resumes it reads past the rest.

The driver runs the function (RunConsumer), and each pull goes through the driver's Runner. Each chunk is a copy, so it can be kept. Pulling the same part of the stream twice, or pulling after the function has returned, throws ResultAbandoned.

consume for a value already read whole: the function gets a stream of one chunk, these bytes (none, for an empty value), which it may keep, and the recipe goes on after it with no reading of its own. The driver runs the function as it runs consume's, and the stream has the same rules, but the function never pulls from the response, so a driver can run it among the rows it has already read. This is what streamField does with a value small enough to read whole first, where consume's references, masked pulls and drain per value cost several times what the value does.

A recipe chosen at run time, such as a column's prepared recipe, which GHC therefore calls without seeing into it. Wrapping it here costs nothing in the recipe and saves the 16 bytes that the call would otherwise allocate for its position. Leave it off a recipe GHC can inline, because there the wrapper only adds a table lookup.

The same recipe, for one that is built to be run once, such as a step of a loop that builds the rest of a row's recipe as it reads. GHC then takes the recipe's input along with the function's own arguments, rather than build the recipe as closures and thunks and run it after. On a recipe that runs more than once, such as a prepared one, the work before its input would be repeated for every run.

Fail with a value that was read but can't be used. The bytes after it are left for whatever recover runs next.

Run a recipe, and if a value in it fails (failValue), run the handler from where the failure left the input.

Run a recipe, and give its failed value, if it has one, as a Left.

A recipe that can also read a value of type env with ask, which withEnv supplies when the recipe runs. It reads input and suspends just as a Parser does.

The value given to withEnv. This reads no input.

Supply the environment, which makes the recipe a Parser. The same recipe can be used again with another value.

Use a Parser, such as one of the reads below, inside a Recipe.

The next byte, which is left unread, or Nothing if the message has ended. This is how to look for the next token, because it is the one read for which the end of the message isn't an error.

The next byte, which is left unread. The end of the message is a ProtocolError.

One byte.

A little-endian 16-bit integer, as most integers in TDS are.

A little-endian 32-bit integer.

A little-endian 64-bit integer.

A big-endian 32-bit integer.

Exactly this many bytes (the second argument), in one ByteString. If they lie within the current payload, the result is a slice of it and nothing is copied. Otherwise they are copied into a buffer of their own as they arrive.

The first argument is how much may be allocated before the bytes have arrived, as append describes. It protects against a server that declares a huge length.

A slice keeps its whole packet alive for as long as it is held, so use ownedBytes for anything kept after the current token.

Like bytes, but the result is always cheap to keep, because a slice is copied.

bytes that may allocate the whole length ahead. This is for short metadata whose length field is small enough to bound what a server can ask for, such as the length byte of a B_VARCHAR.

ownedBytes that may allocate the whole length ahead, as boundedBytes may.

Between 1 and this many bytes, as a slice of the current payload, waiting for a payload if there are none left. Asking for zero gives an empty result without needing input. Loop to read more than one payload holds, and copy what you keep.

chunk for a recipe that collects a value. It gives Nothing if the response started being thrown away (Discard) while this read was waiting for input. The recipe should then release what it has collected and skip the rest of the value, because Nothing reads no bytes.

Pass over this many bytes, across any number of payloads, keeping none of them.

Run a recipe this many times and collect the results in order. A negative count is a ProtocolError.

A B_VARCHAR: a string of UTF-16LE with a one-byte length in characters.

A US_VARCHAR: a string of UTF-16LE with a two-byte length in characters.

Run a recipe on exactly the next n bytes, for a token that declares its own length. The recipe can't read past them, and it is a ProtocolError if it leaves any unread. The bytes are collected first, so this suits short tokens rather than anything large or anything repeated per row. Compare limited.

Run a recipe, with a ProtocolError if it receives more than this many bytes before it finishes. This is for a token with no overall length of its own, so that the lengths inside it can't make the reader wait or collect without end. Unlike isolate, it collects nothing first, and the recipe may finish early.

A value's bytes, and whether they are cheap to keep. Borrowed bytes are a slice of a receive buffer. Nothing overwrites them, but holding them keeps the whole buffer alive. Owned bytes are in a buffer of their own. The difference lets a decoder that keeps bytes copy only when it has to, and lets one that only looks at them, such as an integer's, never copy.

The bytes, to look at now. Keeping them may keep a receive buffer alive.

The bytes, cheap to keep, because Borrowed bytes are copied.

A value of a known length, given the allocation bound of bytes and the length. Nothing means that the response started being thrown away while the value was being assembled. The partial value has been released and its remaining bytes skipped, so the recipe can carry on with what follows.

Read a value of a known length, as bytesValue does, and convert it. A value that lies within the current payload goes to the first conversion as a slice of it, and one that crossed payloads goes to the second, assembled in a buffer of its own. A Left from either is a failed value (failValue) after the bytes, and a value that a drain threw away is ReadDiscarded.

A value that lies in the payload, converted as convertBytes converts one, or else another recipe. Its delimiter is a length prefix of one or two bytes, little-endian, with a value that means NULL, or no prefix and a fixed length: the delimiter arguments are the prefix's width and the NULL value, or 0 and the length. A NULL runs the first recipe after the prefix. A value that doesn't lie wholly in the payload, or any other width, runs the second from the delimiter, which it must read itself. The environment is passed to both recipes unread.

prefixedValue for a column of a row, whose environment is the NBCROW bitmap (empty for a ROW token) and whose first argument is the column's index from zero. A column the bitmap marks NULL has no delimiter, and runs the NULL recipe at once.

A long value being assembled from pieces as they arrive. Use each one only once, because append may write into the same memory and its result replaces its argument. A recipe holding one must not be run twice, as runFrom explains.

Start a value with this declared length, or with an unknown one.

Add a piece to the value, which is copied, so the piece's packet can be released. Use the result in place of the argument.

The first argument bounds what a declared length alone can allocate. A server that declares a huge value and doesn't send it costs that much memory, and after that at most three times what it has actually sent. A value that turns out longer than it declared carries on as a value of unknown length.

The assembled value, which is safe to keep. Don't use the Accumulator again.

Why a value or a row was read past without a result.

A row or value from the server did not fit the requested Haskell type: a column count or SQL type the row type doesn't accept (found when the result set's columns arrive, before any row), or a value that doesn't decode (a NULL for a non-Maybe field, an out-of-range integer, a refineField that said no). The rest of the response is read before it is thrown, so the connection stays usable.

The byte stream from the server could not be interpreted. The connection is unusable afterwards.

A result stream was consumed after a newer request was started on the same connection, which discards any unread results, or after a read of it was interrupted by an asynchronous exception, which cancels the statement (see queryS). Also thrown when pulling again from a stream that was already read to its end.

On a MARS connection (connectMars) a newer request leaves the stream open, so this is thrown only by a stream that was canceled: by cancelResponse or the end of its withQueryS, by cancelActiveStatement, a reset, the rollback of a transaction it was open in, or an interrupted read.