From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: master 1e3b0f2: Improve doc strings of project.el Date: Sat, 18 Jul 2020 22:14:07 +0300 Message-ID: <3ae3a7c3-f8c4-a4de-d8bf-d4d62f8f4c44@yandex.ru> 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> <20200718090546.GC30436@tuxteam.de> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="23754"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0 Cc: emacs-devel@gnu.org To: tomas@tuxteam.de Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Sat Jul 18 21:14:45 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 1jwsIG-00063u-K7 for ged-emacs-devel@m.gmane-mx.org; Sat, 18 Jul 2020 21:14:44 +0200 Original-Received: from localhost ([::1]:40938 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jwsIF-0000Bi-Ll for ged-emacs-devel@m.gmane-mx.org; Sat, 18 Jul 2020 15:14:43 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:52938) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1jwsHl-0008DU-KC for emacs-devel@gnu.org; Sat, 18 Jul 2020 15:14:13 -0400 Original-Received: from mail-ej1-x635.google.com ([2a00:1450:4864:20::635]:38866) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1jwsHj-0007aO-LZ for emacs-devel@gnu.org; Sat, 18 Jul 2020 15:14:13 -0400 Original-Received: by mail-ej1-x635.google.com with SMTP id br7so14218133ejb.5 for ; Sat, 18 Jul 2020 12:14:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=M+mRNkRxRT3lmJa2gYr4fX4r+zpgi7LXU3h2HLSH+Mc=; b=H0Wy7HEPXpuA/NUoeCLJcNGHs2qYbVHJSNqzkgVPym9vRNsIK3dLkN6MNT1IHb6hBD 355TxcAu1tuUVepAIBj4y8C7apCWwryonv1gCwZXY3teZscmvE5VWj0CtSKAOCTxzZku uAeoVPbYbx9jzK6Isr6axjixrrTpYpy6SMLEJEVuOswBHMgLIjKLO6TdWUwySVLhSrhH JdZF9nMY3pD2jxbpcL7BM/IDOGF3IHyIg3FzE8elzZT2mlfo00qvpWDqQ/k66Zc763AU vtxRx0Lxt+jUSr6R5L7VHcAFKEBrVXoP4Lpuxjo2Vok2FokS+8Bv8gqEsRbvK1YeyJ+L v61g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:subject:to:cc:references:from:message-id :date:user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=M+mRNkRxRT3lmJa2gYr4fX4r+zpgi7LXU3h2HLSH+Mc=; b=S8sUo5yboUYNfC3tu/XOiEcQWenyCwE/7Fre7OjDwXv4WPk8JaOZnJ+hjrN71yZhjS yfgBVN1X+AotIvxnDnjtqiBxtuGcEBcxIRfvELWSn27lFauQvKZPVP29hdzeomljxj+O Qh/OB920yPgdD78AgtDjF86jTdkg2o+Zon/VIq2Bw/JyMU5kpuNYMbGYuf5lxJhQki2V 079nWyYEUqJhS8rbtb00NWJfjUOtJJjsf8XIbZaKXdvng1vi3NzeTZbf1HGo50g55Nqr 0TaGqkR9uIxttWKy8aIek7wdAAr5CIsAXLm+31UcEMc8e31SHvHUoEcJUswm5DI4lpmt FCvA== X-Gm-Message-State: AOAM531SsPo0YgW88eEHKlBf1yI35pUozXnUEX6Zjxt5RCSDme5ywTic Jsewmnlwa0kPgslX2QOOAGWQJrhL X-Google-Smtp-Source: ABdhPJxWx8ezI7rUWWTiVk4+eX0DPLnDg5VkNzi3pQaJK6MNHVF+p8lEhjY6Py075Vh8najQgNzlig== X-Received: by 2002:a17:906:4b16:: with SMTP id y22mr14212039eju.4.1595099649633; Sat, 18 Jul 2020 12:14:09 -0700 (PDT) Original-Received: from [192.168.0.3] ([66.205.73.129]) by smtp.googlemail.com with ESMTPSA id d22sm11201649ejc.90.2020.07.18.12.14.07 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Sat, 18 Jul 2020 12:14:08 -0700 (PDT) In-Reply-To: <20200718090546.GC30436@tuxteam.de> Content-Language: en-US Received-SPF: pass client-ip=2a00:1450:4864:20::635; envelope-from=raaahh@gmail.com; helo=mail-ej1-x635.google.com X-detected-operating-system: by eggs.gnu.org: No matching host in p0f cache. That's all we know. X-Spam_score_int: 0 X-Spam_score: 0.0 X-Spam_bar: / X-Spam_report: (0.0 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=1, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no 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:253078 Archived-At: 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 :-) Right. > 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.