[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: master 1e3b0f2: Improve doc strings of project.el

From: Dmitry Gutov
Subject: Re: master 1e3b0f2: Improve doc strings of project.el
Date: Sat, 18 Jul 2020 22:14:07 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

On 18.07.2020 12:05, tomas@tuxteam.de wrote:

The docs say it's represented by a number, but it's not a "real"
number (you never do any arithmetic with it), and an fd can be
backed by very different mediums: a file on disk, a network socket,
a pipe, etc. And everything is a number in C anyway. It's an
"opaque" value.

Yes, this is some kind of OO. But it leaks a couple of things:
first, it's a "small number" (i.e. not some random 64 bit
address, but the pattern of counting up from zero and of building
bitmaps of FDs is considered --mostly-- viable), i.e. the mental
model around is that the kernel "has" a table somewhere indexed
by FD.

So it leaks a little.

This detail wasn't probably intended to leak in the first
place, but was just "the obvious thing to do" in a world in which
machines with a 32 bit address space were considered serious iron.

I think, at best, you are getting a sense that it is a pointer. But one you can't easily dereference.

And there can be just about any data structure behind that pointer.

It's not an ironclad abstraction (fds can have various kinds of properties, as well as slightly-incompatible behaviour, as you have pointed out). Still, it doesn't invite the caller to use whaterver data structure is behind it directly.

When using it in a piece of code, you don't always have to know what
kind of file it is. Or you just know it's a socket, for instance.
But you know there are certain things one can do with a file
descriptor, like passing it to 'write' or 'read'.

Yes, definitely. Barring errors in the interface design (read()
returning zero bytes is "we're done" in the case of a file and
"currently nothing there, but do come back and retry later" for
a socket :-)


My point in all of that is that (some) leak in the abstractions
might lubricate change.

It might, I suppose. But Elisp is pretty transparent, so it's not possible to create a similar barrier anyway.

Writing in the docs "here be dragons, we might well change that
implementation from under you [2]" is fair, and IMO better than
"warranty void if opened" ;-)

At least the doc should state the information that would help the client use the interface correctly first.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]