Suppose you want to write code manipulating iovec vectors of the sort passed to readv() and writev() system calls. If you try man readv you might see something like this:
On my Mac powerbook, the sys/uio.h system header defines iovec as below, which also matches what I see on Linux. (But my Mac's man page for readv() mistakenly says iov_base is char*.)
Wil can't really avoid using this iovec type even though he has a nearly identical yv type defined with lots of convenient methods lacking in iovec. In practice, APIs for interacting with the outside world prefer using arrays of iovec to express discontiguous scatter gather buffers for i/o. In many cases, trying to use yv isn't practical. So an ordered pair (iovec* iov, int len) often acts like a defacto standard type meaning vector of iovecs, and direct support for this is useful.
So þ defines ydvp to represent this iovec vector pair most conveniently. Type y+d+v+p means thorn deck (iovec) vector pointer, which acts like an iterator over iovecs while preserving direct access to the original (iovec* iov, int len) pair.
(Note all þ iterators end in p because they act semantically like pointers. If an STL collection class named foo has an iterator named foo::iterator, in þ the iterator's name is foop with no :: inside because it's not a nested class. Appending v to the end of iovec means a vector of iovecs, and appending p means an iterator over that vector. But ydvp is really just a wrapper for (iovec* iov, int len) plus methods, to work with other types editing iovec format.)
Here's the ydvp class with interspersed comments.
Members p_v and p_n preserve constructor args; p_i is current index; any index >=p_n returns zero length p_nil.
Construction is minimal; assignment and copy construction are encouraged (using the unspecified default definitions which copy memberwise, or using any bitwise copy you like). Destruction is a don't-care, except use after destruction should be brought to your attention.
You can recover constructor args; methods notably begin with a p prefix. (They might have been named pv() and pn().)
Total length in an iovec vector is usually defined as sum of all lengths. If we cached the result, we'd deny options to change iovecs later. (Why should we forbid all changes to iovecs? It's not our call.)
You can copy a current iovec or fetch one at any index.
You can seek the "current" index position by name, addition, or subtraction (operator-=() omitted for brevity). All indexes above p_i are treated the same. (Why not?)
You can increment or decrement (operator--() not shown) the current position. Postfix is deprecated as inefficient, but not punished more than acting like prefix.
(Note these operators return the same result as operator bool(), so we could use while loops instead of for loops, but that would look less like STL usage.)
Conversion to scalar boolean means a test that upward iteration is still underway. (The original version only iterated upward, but no harm is done by adding subtraction operators).
If you want to mimic STL style of testing for iteration end, just return any y0x* pointer from a collection's end() method. Both comparison operators assume a nominal end value argument because otherwise comparison isn't very interesting. (These are here mainly for show, not because uasge is expected.)
The y0x class is an opaque (never defined) type understood everywhere in þ to mean end — the return value from a collection method named end(). (A combination of zero 0 for origin and x for max extent intend to say "original or primordial end" to mean an end value canonically denoting end of any collection. In non-þ naming schemes Wil names it End.)
The most complex parts of the ydvp api involve slice subsets (see the slice demo) and comparison to other sequences (see the compare demo). Slices for ydvp are shown below, but (due to detail) comparing iovecs appears only in the compare demo. Anticipating content of the slice demo, here is the main base yz slice api:
The yz api is longer, but this shows parts of yz affecting subclass ydvpz representing a slice of one ydvp instance. Both z_p and z_p are signed — negative means relative to total sequence length, equal to psum() in the case of ydvp. When either is negative (and thus relative) zabsolute() can convert to positive and absolute; but you might rarely (if ever) use negative values. (See the slice demo).
The meaning of yz is trivial: z_p is a position in the sequence — an offset from the first element, with zero as the origin; and z_n is simply length starting at position z_p. You subclass yz like this:
So the state of ydvpz is just yz plus a pointer to ydvp (but using reference syntax). The idea is to write expressions like this:
... using these ydvp methods not yet shown. The expression just above uses operator()() to return an ydvpz instance:
The ydvpz returned merely copies the input values, so all it does is capture the offset, length, and collection pointer together in a bundle of type ydvpz which means "I'm a slice of ydvp" that can be processed by other methods overloaded to use ydvpz. For example, the rest of the ydvpz adds support for writing and debug printing ydvpz in a manner resembling the same additions to ydvp (shown column right).
The following several pieces of sample code show building, debug printing, and writing ydvpz slices to std yout (out »), and to a local temp yb buffer (see buf). Here two literal C strings provide a source of iovec data used:
Next we build an instance of ydvp as described column right, using yd64vp with a built-in vector of 64 iovecs (cf »).
The middle two lines above append iovecs for small slices from the yv instances; the last line writes this on stdout:
Next we make a one kilobyte buffer and write this content into it with yb::bappend() (buf ») before debug printing the buf.
The last line calls yb::pdump() which writes this output. (The trailing ynow flushes the buffer in out stream yout.) Note crc checksum 0xdff31f7f is identical to that in our ydvp.
Now we finally reached the slice example, which is stored in variable pz for clarity. Then pz is written to a new buffer instance. (We could have re-used the old buffer, but this way we show less new api.)
The final line above writes the next output, differing from the last dump only by containing less content, matching the slice described:
But that's how content looks when dumped from a buffer. When we cite or quote the slice below, we can see internal ydvpz structure — minimal in the case of cite but fully detailed for dump.
The output of those two lines is shown below. But where did the ydvp come from inside the dump? Well ydvpz::zdump() actually generates the ydvp described by the slice on the fly, as we'll see soon.
However, before we dive into source code for dumping slices and generating new ydvp instances on the fly, first let's look at what happens when you write that ydvpz to an instance of yfdw for stdout:
Wil wrote almost all of the fd demo just for that last line of code whose operator<<() calls yfdw::wput() using system call writev() to do the work (fd «). Unsurprisingly, this line appears on stdout:
Let's drill down into code writing that line, so you can see how ydvpz slices actually work in terms of generating new temp ydvp instances on the stack (using subclasses like yd64vp, column right: cf »).
This is the part of the fd demo reserved for this page. (The rest of that demo sets the stage for code below.) This yfdw.h inline operator:
... calls this yfdw::wput() entry point:
Which calls one of the two helper methods below, depending on size of stack allocation needed. These versions explicitly declare arrays of iovec instead of using ydvp subclasses yd1024vp and yd32Kvp:
In both these helper methods the interesting bit looks like:
This creates a new empty ydvp on the stack and uses pcut() to render the ydvpz slice argument as a fresh temp iovec vector. In fact, debug print code for ydvpz uses method prender() for i/o:
ydvp subclasses with built-in iovec vectors have a constructor that calls prender() above directly. So just instantiation can do i/o.
Mildly gnarly pcut() generates a new subset from a slice:
(Code for yz::zabsolute() appears in the slice demo: cf ».)
But that just converts a relative slice (with negative values) to an absolute form before calling the real pcut() below, which is the main support for ydvpz slices, all of which route here:
Since this page already runs long, little detail in pcut() is explained. First length p_n is set to zero (in case it wasn't already) so new iovecs can be appended with padd() whose code appears column right (cf »). Then pos bytes are skipped to find the starting offset of content in the slice. This might exhaust all the iovecs if pos exceeds old psum().
The second loop simply counts out the desired number of bytes, appending iovecs until the new psum() is established.
Many overloaded pcut() methods route to the main one:
More ydvp api appears in other demos, when detail is specific to those topics. For example, the rand demo will feature pseudo random permutation of iovecs, along with other techniques for stream randomization.
Source code for ydvp hasn't been shown yet. It appears below, and isn't long since the complex parts are done by ydvp::pcut() in the last section above. Most slice code prints or writes code — in each case this involves generating a new ydvp first in a temp stack instance, once again using ydvp::pcut(). However, this time pcut() gets called indirectly via prender() (cf «), or via constructors for ydvp subclasses that call prender().
Unlike the fd demo — which only handled two different sizes of iovec vectors (1K and 32K) — the slice code below uses more gradations in size for temp stack iovec vectors. This makes the code longer (and that's why fewer cases were shown in the fd demo).
One line is written by zcite() and zprint() is just a shallow wrapper around pdump() that curries the standard yout argument, so it's easily used from gdb.
Helper functions are called to process content in iovecs. Different functions are called depending on the size of temp stack array needed. There are other ways to do this, but this one is simple and works. Most of the time, under normal circumstances, the first z256() helper method will be called, because 256 is large for iovec vectors.
The final 64K helper is handled differently for contrast. In each case the quo arg means quoted (ie for debug print) to request a dump of iovec content instead of writing iovec content, so zdump() can share these helpers with with zout() shown next.
Code for zout() is identical to with zdump() except for false passed to each helper method, causing content of iovecs to be written without interpretation. As before, z256() is the normal case.
The license for all C++ code on this page is the same as that for all C++ on this site. Please read the license page carefully before you use code — the BriarPig mu-babel license resembles no other open source license. You only have permission to use the code if you agree with all the license terms. And as always:
(This conversation with Dex clarifies nothing, and is likely a complete waste of your time. It wasted Wil's time — such conversations with Dex rarely have any value beyond bits of humor, explaining why Wil doesn't like chatting about software to no purpose. A shorter and slightly more constructive dialog follows this one.)
"So what did you think?" Wil asked Dex at demo's end.
"Well," Dex sniffed, "I'm a little offended you didn't ask what I thought earlier, when I could have helped."
"Help do what?" asked Wil, genuinely puzzled.
"Um, you know, help suggest a better api," Dex shrugged.
"To clean up the ungainly parts, I suppose," Wil suggested.
"No," Dex laughed, "when it comes to iovecs, I like the traditional approach, which is painfully awkward, as you know."
"Okay, you mean like, 'Grr, I love to write in C, so gimme those naked C iovecs without any objects — I can take it like a man.' Something like that?" offered Wil.
"Heh," Dex grinned, "yeah, basically."
"Why am I not surprised?" Wil monotoned.
"You just don't get it," Dex explained. "The idea is to show how smart you are by doing everything the hard way. When you use objects you must overdo it; and in low level C stuff you must not use objects at all. But you're using objects the right amount — which is wrong if you want to grandstand like I always do."
"So what's your point?" Wil prompted.
"My point is slices are creepy," Dex replied.
"That's a change in subject," Wil objected.
"Yes," Dex agreed. "But I didn't think you'd call me on it. It's very rude of you to notice when I evade questions with random topic swerves like that. It's better when you just go defensive like I wanted."
"Okay," Wil joked, "I'll try to remember."
"I hope you don't expect me to use your iovec slices for stack buffer i/o to avoid buffer overflow problems," Dex said.
"I wouldn't dream of it," Wil pretended. "I know how much you enjoy those buffer overflow fire drills."
"I'm just kidding," Dex joshed. "Humor me, but don't overdo it since my dumb remarks reverberate a little."
A short silence descended as Wil waited to see if Dex had anything else to say, while Dex looked around to see whether anyone was around. Maybe he looked for Ira. Nope, no police around.
"I was thinking," Dex proposed slowly, "maybe you should rework all this as a large and exhaustively thorough i/o framework because that would be cool and gnarly and establish your chops."
"Not interested," Wil shrugged.
"Not interested in chops?!" Dex asked incredulously.
"No, I have chops," Wil countered. "I don't care about establishing them. Bor-r-ring. Also, I don't need a framework."
Dex snorted. "Yeah, right," he disagreed. "We all need frameworks. You're naked without one. What would people say?"
"Oh, who cares?" Wil dismissed. "Other stuff in þ might look more like a framework. Seems like a disadvantage, though."
"You overdo heresy a little," Dex complained.
"Useful stuff should look like part of a language," Wil continued. "Not like a suit of armor shielding you from being involved."
"You even mention English long bow versus knight's armor again, and I'm outa here," Dex warned.
"Tempting," Wil noted, "but too easy. Framework sounds too rigid and I'm into really lightweight stuff. I only want enough form to avoid errors, but not so much attention is channeled without flexible options remaining visible. I don't have a key metaphor."
Dex raised his hands and made scare quotes with his fingers. "'The medium is the message,'" Dex suggested archly.
"Or 'design patterns über alles' slogans," Wil said.
"Blah, blah, blah," Dex agreed against form.
Wil winced. "Don't say that," Wil pleaded. "I hate that phrase."
"I feel a cliché phrase binge coming on," Dex warned.
Wil stuck his fingers in his ears and waited, peeking. Dex looked up and mimed whistling until Wil stopped.
"So what do you call your method?" Dex asked finally.
"No name yet," Wil shrugged. "I'll think about it."
"Is this the longest demo you plan to write?" asked Stu.
"Yes," confirmed Wil. "I'd expected a bit less."
"Long from showing so many iovec classes?" prompted Stu.
"Yes, and I could have skipped some," noted Wil. "But by including all of them I introduced themes priming many other demos. So this one creates a horizontal slice of good context motivating several other classes. Though a long intro, it might unify what follows."
"Ever use yz's slice api in the workplace before?" asked Stu.
"No, but I usually port ydvp and ydvo to most work environments," replied Wil. "At work it's best to introduce the smallest amount of code that gets a thing done. So I usually add the effect of slicing but I don't include the yz class."
"Because it's abstraction?" Stu guessed.
"Yes, abstraction is shunned most places," Wil agreed. "And because operator overloading gets little favor either — and slices are less useful without more overloading."
"Operator overloading sucks," Stu agreed.
"Yes, I think that's what Dex found creepy," mused Wil.
"Then why use it?" Stu pursued.
"Operator overloading clarifies when used consistently and sparingly," explained Wil. "I mainly use it for stream processing, to simplify sequence editing and copying."
"Using operator()() looks disturbingly like a function call," Stu wrinkled his nose. "It's ugly to C coders."
"Well it makes slice notation concise," Wil defended. "I'd use operator[]() instead, but that only takes one argument, and I need both position and length."
"I agree it's concise," Stu granted. "But then there's operator<<() — you use it everwhere. Could it be overkill?"
"My task is usually 'copy source to destination' and << expresses that fine," Wil explained. "The only thing that changes is type of source and destination, and whether you mean form or content."
"I'd rather see the actual method names," Stu said.
"You can unify generally or itemize specifically, but not both," Wil shrugged. "I'd rather reduce code with generality."
All this code is available only under the BriarPig mu-babel license described fully on the rights page. You do not have permission to reprint this page in any way. Neither feeds nor repackaging is allowed. You can link this page if you want folks to read it.
thorn: todo, names, fd, iovec « Þ, assert, log, run, hex, crc, buf, in, out, quote, escape, compare, file, deck, cow, arc, blob, tree, slice, rand, time, stat, hash, heap, node, primes, page, book, pile, stack, atomic, lock, mutex, thread, map, meter, list, iter, ctype
(mu: toy, peg, imm, tag, box, symbol, token, number, bigint, class, method, reader, writer, eval, env, vm, gc, world, pcode, compiler, asm, lathe, lisp, smalltalk, design, weight, jar, card, harp, debug, profile)
Some demos are stubs: todo is a demo guide. See toy for mu updates on language pages; names introduces naming schemes.
Here Wil first tried friendlier but longer name yiovecvp, but later gave up and changed the name back to ydvp when appending letters (eg ydvpz for a slice) got even harder to read. Note ydvp is the original name Wil used a few years ago when writing yd and related classes (described in deck), when it meant thorn deck (iovec) vector pointer for the iterator over an iovec vector inside yd. In other words, the word iovec doesn't even appear in the name despite being central.
If it's easier to memorize, you might try a neologism data for the d inside ydvp, as if referring to one iovec. But that's not really it. Just tell yourself: it's a iovec vector iter used by yd decks, which just happens to be something completely generic and useful apart from yd.
The most interesting thing about ydvp is a model it shares with many other þ types: it represents an ordered sequence of some N bytes that can be read or written, which can described in terms of subsets (called slices) expressed as offsets into the original plus a length.
In other words, iovec vectors in themselves are a bit dull; how they resemble other byte sequences — and moving content back and forth between them — is of more interest. The purpose of iovec vectors in scatter-gather i/o is skipping any staging to make N bytes contiguous in memory just to invoke an api that reads or writes those N bytes. Location in memory wherever it sits now should be just fine; it might already be staged just the way you want it for some other purpose.
Demos here focus on treatment of a byte sequence in ydvp as a single thing, despite representation as a vector of N parts. Other than eof or end of stream, no position in ydvp is distinguished as a cursor for reading and writing.
Also in common with other byte sequence types is general separation of memory ownership from use and manipulation. You might feel tempted to build memory allocation semantics into classes like ydvp because it seems missing to you (because you never want to deal with it). Owning space is a role for some other class. This kind of scatter-gather api should be able to work on many kinds of physical representation — interoperating between them — as long as memory involved doesn't move while iovecs are using it.
Expected ydvp iteration usage looks like this:
And this has essentially the same effect as this:
The latter plain version is arguably simpler. So what's a practical reason to use ydvp? The packaging is better, and you can subclass ydvp to do something interesting (like represent subsets of an iovec). The advantage of packaging is subtle:
As a single value instead of pair (iovec* iov, int len), now you can manipulate that single value very conveniently. For example, if you pass it to other methods, now you can ensure they stay together, paired with each other instead of other values.
More conveniently, ydvp can be used as the left hand or right hand side of expressions, and you can overload as many binary operators as you like to take ydvp as a source or destination operand. Since þ uses operator<<() most commonly in this way, all the examples below will use this operator.
For sake of argument, assume þ has this operator defined:
On top of this, we can build the following operator:
Whose implementation could look like this:
You can see more api for out stream yo on out when it's done. But just like this operator, we can define many other similar operators for any consumer of octet sequences. (Some might be able to process more than one iovec at once, in which case it's best to express intent this way with operator<<() instead of forcing a loop and explicitly sync i/o.)
Wil added several new ydvp methods to the api just for this demo, so usage examples can be shown with little code. This section shows appending new iovecs to an existing vector, which required adding new member p_x to distinguish max physical capacity from current p_n logical length. (It's the same distinction as that between physical size b_x in a buf and logical length v_n in a run.)
The following sample shows building a ydvp instance by:
- allocating a stack-based iovec vector for raw space
- constructing an empty ydvp with this raw iovec space
- making yv sources for iovecs (see the run demo)
- appending new iovec instances by copying the yv's
- printing ydvp (see quoting next section and quote)
- flush the yout std out stream (see the out demo)
The output of [5] appears below, and is discussed in the following section on quoting and debug printing. This output is untouched other than being run through yfdw::whtml() shown in the last demo (fd «). Proper indentation is handled by all object dump methods for better readability. Hex dumping is shown in the hex demo, and checksum generation is shown in the crc demo. (The topmost crc value shown here checksums all content regardless of form.)
Code for ydvp::pdump() appears below in this column (cf »).
Let's repeat the two sample lines actually appending new iovecs to the ydvp so we can show both the new api and actual code for building:
Those two lines invoke two variants of padd() methods in the ydvp api, by way of operator<<() inlines right after the class declaration:
Notice we also support operator<<() for ydvp on the right hand side (rhs) and not just single iovecs. The two iovec versions are simple:
Adding all iovecs in another ydvp is just as trivial. We return the total count of iovecs actually added, in case a caller wants to know:
Though sample code above shows an iovec vector allocated separately from ydvp, you can allocate them together using ydvp subclasses defined in ydv.h that include built-in iovec vectors. For example, here are the first two which have 64 and 256 iovecs inside:
These ydvp subclasses with in-built iovec vectors are used by slice methods (see left column) to allocate temporary stack iovec vectors when building the subset described by a slice. Which version gets used depends on size of the original iovec vector — a slice will never be longer than the original, which helps explain use of ydvpz::z256() (and related helper methods) which allocates an instance of yd256vp when slicing ydvp with size under 256 (cf «). The inherited prender() call in the yd256vp constructor also appears column left (cf «).
Wil likes how easy it is to write iovecs to an output stream using earlier code. But Wil also wants to be able to write a debug description of iovec vector structure to an out stream. So given an instance of ydvp named src, Wil wants to debug print it with this syntax (see quote for more on quoting):
To make this work, Wil needs a debug printing ydvp method named pdump() and a new type for overloading operator<<() to call pdump(). So Wil adds the following to the class api:
Of course, Wil did not try to make this look pretty. Partly this is because it's boilerplate — virtually every þ class worth printing has something like this in it.
By convention, þ nested classes start uppercase with the same prefix as the methods. Also by convention, the quote wrapper class is just named q after the leading uppercase prefix. The quote() method simply does an inline wrap of the object's reference, so sizeof(Pq) is just the size of a pointer: sizeof(ydvp*). A compiler needn't even really construct an instance of struct Pq when the only thing that happens is passing the q_p ref to another method.
The whole thing is just a dance with types to make overloading work. And because it's for debug printing, Wil doesn't care whether a compiler does indeed optimize the code — it's not going to matter. All that matters is how easily Wil can print what he wants with least effort. And it's nice this support is easy to clone from class to class.
The pcite() and pprint() mehods are also shown because they're always present when a dump() method is defined. By convention, cite() is always one line, and print() is for use under gdb (writing to stdout by one or another means) which calls dump().
Next is code to dump or cite — fine detail might be unclear until the crc, hex, out, or quote demos. Sample output appears above (cf «).
Obviously this takes the yo api in out for granted. Think of yo::of() as fprintf(), with a variant named yo::oft() increasing indent level by one afterward — here t means tab. Dumping each iovec is done by yv::vshow() in the hex demo. The crc is generated by ydvp::pcrc() shown in the next section below; however, that uses api from the crc demo.
But first let's show implementations of pcite() and pprint() (which uses the standard yout stream from the out demo).
Unlike a full debug print by pdump() invoked by a line like this:
... a one line print by pcite() is requested with this syntax:
which is based on template ycite() in mu.h and another operator<<() inline in ydv.h overloading yct<ydvp> as a rhs source:
This is clearly rather baroque as a means of making ycite(src) work as a rhs value for overloaded operators. But since only one line of inline C++ is needed per class to call a cite() method, this is quite terse — as boilerplate goes — even if the ycite() template looks obtuse.
Here we use the yh32 api in the crc demo to find the crc32 hash of ydvp content in the entire sequence. The ydvp::pcrc() method is used by another operator<<() inline as shown below.
Did you think it would be more complex? The inline operator<<() methods from ydv.h and yh32.h are defined as follows:
Below is the subset of yh32's api in the crc demo related to iovec. (This is taking quite a lot from that demo, but at least this is clear.)
Note some processors have built-in crc32 instructions — you should use them when available. Otherwise code from zlib is good.
Here Wil shows an odd but powerful member of ydv.h iovec classes (all first drafted in this form in 2004). This version of ydvo hasn't changed as many times as other classes in this demo. So ydvo is little integrated with other þ classes like yo in the out demo. It writes space described by ydvp using an api like yo — but it's not a yo subclass. (The out demo might include a class named ydvpo that is a yo subclass closely resembling ydvo shown here. If nothing else, you should get an idea Wil sees many ways to do a thing with small variations.)
Before api and code for ydvo, let's first show an example of intended use, with the actual output written by this sample code. What you'll see is this:
- populate a destination yb buffer with lowercase letters.
- populate a source yv run with uppercase letters.
- populate a ydvp destination with slices of lower buffer yb.
- populate a ydvp source with slices of the uppercase yv.
- create a ydvo out stream for the destination ydvp.
- write the source ydvp to the out stream ydvo.
- show the changes in both destination yb and ydvp.
The interesting part? Source and destination iovec vectors will share neither total length nor single iovec sizes, so it's scatter-gather to scatter-gather.
Those are the lower and uppercase octet strings; vhi is the source sliced below. Let's fill a destination buffer with bytes from vlo:
The last line's debug print looks like this:
(This part of the demo shortens hex characters per line to 12 from 16 shown earlier in this demo, to use fewer horizontal columns.)
Now we make a destination ydvp for iovecs describing slices of this buffer, so we can write them below with ydvo:
Dumping pdest prints the following on stdout. Note memory addresses for slices correspond to spots in the buffer above.
The source ydvp comes next, using iovec sizes that are not the same size as those in pdest shown above. Note we feel free to use iovecs slicing space in immutable static C strings, since we won't be writing them.
Dumping psrc shows the following internal ydvp structure:
The next two lines create a ydvo out stream writing to pdest, then writes the source iovecs to the stream. After that, both destinations are dumped — the iovec vector and the buffer into which it points.
Note how the six byte iovecs in the source flow into the five byte iovecs of the destination. As you can see in output for b1K, the previous lowercase content is untouched outside what was described by pdest. Because the source was larger than the destination, the last three bytes of the source were just ignored since no place could be found to put them.
The most obvious use of ydvo out streams? Updating content in pre-staged layouts, touching nothing outside ydvp iovec vector stencils.
Here's code and interface for ydvo:
The actual number of bytes written to ydvo is returned by oactual(), but it's seldom up-to-date until after oflush() is called.
No constructor takes a ydvpz slice because we don't want to generate space for the copy here. So presumably a caller will use one of the ydvp subclasses with a constructor calling prender() to convert a slice to a new iterator.
Methods starting with underscores are usually private and internal. These internal methods are exposed as relatively harmless. Note ydvo::_oc() strongly resembles virtual method yo::_oc() in the out demo, which handles contiguous buffer exhaustion.
Writing one byte is done by inline yo::oc(), which is important for the following reason: the design of ydvo revolves around this inline — reading and writing bytes by inline pointer bumping is the main purpose for describing buffers by origin and max pointers in all þ stream classes. (It was one of the lessons learned from horrible Taligent i/o performance: primitive operations should not be virtual.)
Convenience operator<<() inlines follow the class:
The constructors have little substance. Each starts by populating the buffer with the first iovec, so origin o_0 points at the first byte and max o_x points one after the last. Pointer o_p starts at the origin and works toward o_x as a cursor. When the current buffer is exhausted, ydvo::_onext() loads the next iovec if any.
Writing ydpv just writes each iovec in turn:
Each inbound iovec is written by owrite() which loops over input fragments, advancing the destination iovec buffers with _onext() as necessary each time one is exhausted. When iovecs have substantial length, all the time spent using ydvo appears inside the call to ::memcpy(), which actually moves the bytes involved. (Note the assumption source and destination bytes will never overlap — otherwise we'd have to use ::memmove() instead.)
In other words, as complex as code in this demo might look, time accrues mainly to moving bytes in ::memcpy() — all other decision-making costs little. (This does have far-reaching consequences when you think about it.)
Advancing to the next iovec in the destination occurs in _onext() which begins with an inline flush to keep o_actual correct — it counts the number of bytes by which o_p has ever been advanced ahead of origin o_0. (This occurs a byte at a time in inline ydvo::oc(), which doesn't count bytes since it can be put off.)
When writing a single byte via inline oc() exhausts the current buffer, the fallback is _oc() below, which resembles the flushbuf primitive in standard C library macros, except _onext() above actually replenishes the buffer. The cost of this call is amortized over the many times oc() is called without exhausting the buffer, when all the i/o is done one byte at a time.
Flushing ydvo resembles flushing a ybo out stream writing to a yb buffer (see out for ybo and buf for yb): the final tally in size isn't right until the effect of bytewise writes can be gauged by measuring how far the pointer of cursor o_p has moved from origin o_0. The subtle line is updating o_0 to match o_p so those bytes won't be counted again by a later flush.
"Did I mention your naming scheme sucks?" Dex shot.
"Not yet," Wil said. "I thought you forgot."
demos « Þ
+ todo
+ names
+ fd
+ iovec « Þ
+ assert
+ log
+ run
+ hex
+ crc
+ buf
+ in
+ out
+ quote
+ escape
+ compare
+ file
+ deck
+ cow
+ arc
+ blob
+ tree
+ slice
+ rand
+ time
+ stat
+ hash
+ heap
+ node
+ primes
+ page
+ book
+ pile
+ stack
+ atomic
+ lock
+ mutex
+ thread
+ map
+ meter
+ list
+ iter
+ ctype