From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: tomas@tuxteam.de Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sat, 18 Jul 2020 11:05:46 +0200 Message-ID: <20200718090546.GC30436@tuxteam.de> References: <5d59dd9b-0848-691a-615e-c16d2070b92d@yandex.ru> <837dv8oida.fsf@gnu.org> <834kqcoghk.fsf@gnu.org> <99bb8976-580a-ef8e-6b7d-130c3ca5cb8a@yandex.ru> <83y2nom3hy.fsf@gnu.org> <20200713075842.GA4332@tuxteam.de> <21b47cbb-d1aa-d875-2944-deebb7583961@yandex.ru> <20200717152702.GA18658@tuxteam.de> <922bca06-3425-6fa3-b184-89942c75e91d@yandex.ru> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="96YOpH+ONegL0A3E" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4882"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mutt/1.5.21 (2010-09-15) Cc: emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 18 11:06:33 2020 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jwinh-0001Cp-5e for ged-emacs-devel@m.gmane-mx.org; Sat, 18 Jul 2020 11:06:33 +0200 Original-Received: from localhost ([::1]:36778 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwing-0002g0-6u for ged-emacs-devel@m.gmane-mx.org; Sat, 18 Jul 2020 05:06:32 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:45014) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwin8-0002Gi-8m for emacs-devel@gnu.org; Sat, 18 Jul 2020 05:05:58 -0400 Original-Received: from mail.tuxteam.de ([5.199.139.25]:41079) by eggs.gnu.org with esmtps (TLS1.2:DHE_RSA_AES_128_CBC_SHA1:128) (Exim 4.90_1) (envelope-from ) id 1jwin5-0004WS-GN for emacs-devel@gnu.org; Sat, 18 Jul 2020 05:05:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tuxteam.de; s=mail; h=In-Reply-To:Content-Type:MIME-Version:References:Message-ID:Subject:Cc:To:From:Date; bh=bTzpVy39ZbcaiE1nEYEXQyS+T3rhAjujg9gqSBSe4iE=; b=RGgcPMzd6L9Fb+55o+dykI+OhLACfdcb/R1enlpQ7sBNsocJhZ+LBcs5k6J9qgvRU31S9gz5siHl+MhNrp0sNyPG0jSrgBUpgRxL2NCK9SzTkh0rlwx65XXcnEfptr0yiitlyFWmBMNO0zCKx3/4c6kn2H60pzBK6MfNc86J8e4NiN2vGWFBTT40XGiWFnOozSV5FmndWmoZaL/hM/9X4GgV2tx60FgMtgoeIgLiQ/2Clhd2XrdUv7VWizVADBQEsnSa1JkTAYCuijMrFGQeH5jMQtl5ZMGsifBNvsAAd0pCqVEikO7Cxg9jFBwfTi2wqCXo90nKy2F88b9KSJeZQQ==; Original-Received: from tomas by mail.tuxteam.de with local (Exim 4.80) (envelope-from ) id 1jwimx-0008Ry-01; Sat, 18 Jul 2020 11:05:47 +0200 Content-Disposition: inline In-Reply-To: <922bca06-3425-6fa3-b184-89942c75e91d@yandex.ru> Received-SPF: pass client-ip=5.199.139.25; envelope-from=tomas@tuxteam.de; helo=mail.tuxteam.de X-detected-operating-system: by eggs.gnu.org: First seen = 2020/07/18 05:05:47 X-ACL-Warn: Detected OS = Linux 3.1-3.10 [fuzzy] X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:253068 Archived-At: --96YOpH+ONegL0A3E Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Jul 18, 2020 at 03:55:33AM +0300, Dmitry Gutov wrote: > On 17.07.2020 18:27, tomas@tuxteam.de wrote: > >I was rather trying to highlight the contrast between (a) the library > >designer(s) set the interface design and (b) the interface evolves > >as a collective effort of designers and users. >=20 > An interface's ability to evolve over time isn't entirely predicated > on there being no limitations on its use. It can easily change as a > result of user feedback anyway. Definitely. But it's not an abrupt transition. > >Reality will be a mix > >of both, of course. The term API conveys a hierarchy -- clearly in > >camp (a). > > > >The "system programmer" thing comes from former times, yes. >=20 > BTW, lower level programming is not devoid of abstractions as well. Absolutely. We are in violent agreement. It's "turtles all the way down [1]". > I could be wrong in some details here, but a file descriptor seems > like a prime example of an abstraction. Well, that's at the Mother of Abstraction, aka the user space/kernel space barrier :-) This one is especially interesting because here you have different applications which dont quite trust each other. You will see that (sometimes ugly) pattern repeat whenever you have a similar situation (web browser, I'm looking at you). > 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. 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. So it somehow creatively leaked. Cf. the select() system call for a (mis?)use of this leak in a very creative way which gave us fun for at least 15 to 20 years. These days it's on its way out. Times change. > 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. 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" ;-) Cheers [1] https://xkcd.com/1416/ [2] ...but by all means, if you enjoy dragons, go ahead :) -- tom=C3=A1s --96YOpH+ONegL0A3E Content-Type: application/pgp-signature; name="signature.asc" Content-Description: Digital signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) iEYEARECAAYFAl8Su2oACgkQBcgs9XrR2kbuuQCeMrFVHQF/coGz57trHnJtnpNx 0U8AniNWiB6QlGwxS4RHbgvQS78Xjjb0 =cbnN -----END PGP SIGNATURE----- --96YOpH+ONegL0A3E--