Dear Marc and Gambit community,

Here comes a subject of meditation for the weekend. As to maximize clarity and discussability I'll split it in two emails. Here we go:

How do we make Gambit port-based protocol wrapper Gambit ports with great performance and as solid abstractions?

Various forms of byte- and character-stream based protocols, such as communication protocols like SSL channels, or encodings like GZIP, probably accounts for in the range ~35% of all Gambit use, so it's central and even critical stuff.

If all of this can be not just whimsical special-purpose modules but be implemented in the united format of Gambit ports, *alot* would be won: Gambit's IO API is really neat and complete in nature: Being able to deliver also these completely central uses through it would be of enormous practical value.

Perhaps even everything needed for this is in Gambit already and we pretty much only need to make a bit of documentation and examples and this way we can all enjoy easily pluggable modules for the rich diversity of uses that are in this field.

To stimulate the conversation and add context, below I'll reflect my long experience of this kind of use and a proposal for qualities that such an abstraction mechanism needs.

I hope you share the enjoyment and appreciation of this topic, and look forward to any discussion that ensues.

*Experience of protocol wrapper Gambit ports using open-u8vector-pipe**: Super easy to implement, and delivers beyond unacceptably badly in the respect that it's not suitable for real-world use ever.* Briefly, over the last years I used Gambit for doing SSL over TCP. A typical, elementary and critical use case for this is HTTPS client/server.

Til now I've essentially made two SSL modules for Gambit, both atop OpenSSL. Total time invested is somewhere in the range 100 - 150 man hours, a lot due great complexity of and lack of documentation in how the OpenSSL library is used in particular in nonblocking mode.

The first one was made based on a bidirectional byte channel Gambit port as generated by Gambit's |open-u8vector-pipe|.

Put very briefly, my experience with it was that

* It had a low transfer speed performance and high latency - probably because of the extra round through Gambit's scheduler needed for every piece of IO done, as compared with just using a native Gambit port such as a TCP client port directly -, and,

* It had all the pains of a leaky abstraction, such as, that when either party would close the channel, it was not necessarily propagated to this channel as the |read-subu8vector| would not necessarily return straight away nor have a return value clearly reflecting that the connection was closed, so actual freeing of this port could take a while. I don't remember the exact details of this at the moment, but the constant feeling was like, uh oh, OMG what's that object on the heap doing now really plus the discomfort of knowing it's possible it's not quite right and of not having a clue - I believe you have similar experiences from your own encounters with leaky abstractions.

So briefly, my experience of |open-u8vector-pipe| for providing a protocol wrapper atop Gambit ports was completely unsatisfactory, and provided motivation for exploring an alternative implementation path later. So..

*Experience of protocol wrapper Gambit ports using custom "io-primitives" structures with a closure for each IO routine: Delivers great but will never be universal between projects* The second one, completed very recently, was built on the concept of that the Gambit port is wrapped into an "io-primitives" structure that contains one closure for each IO method: IO of u8vector chunks, and of ISO-8859-1/ANSI/8-bit encoded characters at the level of character, line and string, for complete definition see [1].

The benefits here are quite tremendously good: The io-primitives code itself accesses Gambit's IO routines directly, and thus

* Latency is ~zero, excellent. Also, thanks to the same thing,

* Both the beneficiary code and the io-primitives code follows IO behavior directly, making the entire abstraction not leak but be solid. Introspection for instance is piece of cake as execution passes directly between the layers of port abstraction - that's easy to understand due to the sequential nature of the execution, it's easy to log meaningfully and to work with in the interactive debugger.

Now, after having implemented this and had these basically very good experiences, it became/was completely evident that this is and will remain a special purpose code, as Gambit's built-in IO API is so good in itself. And really, these io-primitives could be mapped to Gambit's IO exports, it's quite the same thing really, so if that can be done in a way that really delivers it's completely preferable. Thus this proposition:

*Proposed characteristics for Gambit protocol wrapper port functionality* So, now here are the primary things that come to my mind about what protocol wrapper support ought to include:

* Provision of application-layer ports exported through Gambit's IO routines

* These ports can export individual Gambit IO routines i.e. can provide a specific read-char, read-u8, read-subu8vector, read-line behavior, so that a call e.g. (read-subu8vector u8v start end port) leads directly to |mycustomimplementation-read-subu8vector|. Part of the point with this is that,

* Double-buffering and copying must be kept to a minimum as it brings all kinds of expense and complexity - a "protocol wrapper" like this, for example an SSL wrapper, must not be required to work with the beneficiary code via a buffer, but must be let to deal with buffering as it wants to. Furthermore I'd say that,

* Due to the dual nature of a lot of protocols, the API must be in a hybrid binary-character mode i.e. binary IO (i.e. read/write-subu8vector) must be combinable with character IO, at least for 8bit-fixedsize-character i.e. ISO-8859-1 encoding.

This is not a must though - even if a bit of work, binary mode only would be fine, and the user can just wrap read-u8 to read-char etc., this is easy enough to do really.

And last, I'd guess that

* There must be a way to implement these ports in such a way that any IO made of them does not use mutexes at all (i.e. can be run in non-threadsafe mode), and, can be done with not so many trampolines happening. The reason for this is performance:

The default |read-char| implementation whose design involves both mutex locking and trampolines on each call, delivers unacceptably low performance (approximately 200KB/second on laptop CPU core), while a direct implementation approach would deliver approx 25MB/second on the same core which is really good. (Disclaimer: these two numbers are taken off the top of my head from 5 years ago, though should apply now.)

Mutexes can be addressed now, and trampolines probably better wait til the native backend is around, where module-to-module calls don't involve trampolines anymore anyhow, and I guess these parts of Gambit's runtime can be run under that backend at that time.

*Rough proposition of API, draft*

(make-custom-port #!key read-subu8vector read-substring read-u8 read-char peek-char read-line write-subu8vector write-substring write-u8 write-char force-output close-input-port close-output-port close-port input-port-timeout-set! output-port-timeout-set! ) => gambit-port

Note the absence of read and write here - those deal with objects and are not in the scope of this port abstraction mechanism.

It would not be an issue that a particular protocol wrapper port implementation would only implement some of the involved functionality, such as only byte and no character IO; if anything is needed it can be implemented later, the important thing here is for Gambit to provide a format for this that encompasses all this area of use in a performant and qualitative way and thus is suitable for cross-module, cross-project use.

*Example* With this approach it'd be something like

(let* ((client (open-tcp-client "wikipedia.org:443")) (ssl-channel (open-ssl-channel client))) (display "POST /someform HTTP/1.1\nHost: wikipedia.org\nContent-Length: 100\n\n" ssl-channel) (write-subu8vector postdata 0 (u8vector-length postdata) ssl-channel) (force-output ssl-channel 1) (let ((hdr (read-line ssl-channel)) [..]

*Related implementation/code example* For an example of an implementation of a set of IO operation closures akin to what's suggested in this email, see line 61 - 89 of openssl-sack.scm and row 1621 to 1969 of openssl.scm , both attached.

This suits as an example, as as it exports an API extremely similar to Gambit's IO, it is essentially built atop Gambit's IO API in itself, it adds no latency, delivers high performance and performs minimum buffering and copying while providing some hybrid byte and character IO, and can be run in a thread-unsafe mode.

*What do you say?* Now I wish to query you about your take on this:

* What are your thoughts on this topic?

and:

* Marc, how usable is Gambit's included IO abstraction for this kind of use today?

Spontaneously, would you say this can be done right away just given people know how to do it (i.e. documentation), or would adaptations of the IO code be required, if so what kind of adaptations would it be?

Feel free to reflect at high detail what of this can be done already now, perhaps all is ready and it's just a question of getting going with it.

With best regards, Mikael

[1] io-primitives definition used in the particular wrapper described above:

; Name Arguments & Result Behavior ; read-subu8vector (u8v start end #!optional (need 1)) Read u8vector data ; => bytes read or #!eof ; read-substring (str start end #!optional (need 1)) Read string data as ISO-8859-1 ; => bytes read or #!eof ; read-u8 () => byte or #!eof Read a byte ; write-subu8vector (u8v start end) Write u8vector data ; display (v) Write string, number or symbol as ISO-8859-1 ; force-output () Flush any write buffer to network ; close-port () Close port ; make-read-line-until-crlf (#!optional return-eof-on-eof?) Read line until reaching crlf. Permissive behavior. ; => procedure taking no args The procedure returned may be used in a single thread only and thus ; => string or maybe #!eof, see desc reuse the same buffers across invocations. ; If return-eof-on-eof? is set then #!eof is returned in case of EOF. ; If not, string reading is just ended and result is returned.