[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#36392: (info "(elisp)Writing Emacs Primitives") might need some clar
From: |
Basil L. Contovounesios |
Subject: |
bug#36392: (info "(elisp)Writing Emacs Primitives") might need some clarifications |
Date: |
Wed, 26 Jun 2019 19:20:25 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
Eli Zaretskii <eliz@gnu.org> writes:
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Wed, 26 Jun 2019 14:09:03 +0100
>> Cc: 36392@debbugs.gnu.org
>>
>> >From 3d85d73858fe0c126277d04db8b99eeb9f09d672 Mon Sep 17 00:00:00 2001
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Wed, 26 Jun 2019 13:05:51 +0100
>> Subject: [PATCH] Clarify & update (elisp) Writing Emacs Primitives
>>
>> * doc/lispref/internals.texi (Writing Emacs Primitives): Replace
>> outdated For listing with current Fwhile, so that the subsequent
>> paragraph on maybe_quit still applies. Reconcile other code
>> listings with their current source. Fix indentation of sample DEFUN
>> argument lists. Replace ... with @dots{}. Fix argument list of
>> Ffoo example. Describe UNEVALLED special forms as taking a single
>> argument. (bug#36392)
>
> Hmm... I admit that I don't understand the rationale for these
> changes.
>
> Why replace the example? It's a useful example, and I see nothing
> wrong with it per se. The actual code doesn't have maybe_quit
> anymore, but so what? I don't think we should chace every change in
> the sources with our examples in the manual.
Indeed there's nothing wrong with the current example, and I don't feel
too strongly about the change.
Fwhile just happens to be a conveniently similar special form that is
better represented by the paragraph on maybe_quit (not just because
Fwhile currently calls maybe_quit, but also because it epitomises the
need for maybe_quit).
Do you prefer not to switch the example to Fwhile?
>> @@ -863,20 +860,23 @@ Writing Emacs Primitives
>> arguments, there must be one C argument for each Lisp argument, and
>> each argument must be of type @code{Lisp_Object}. (Various macros and
>> functions for creating values of type @code{Lisp_Object} are declared
>> -in the file @file{lisp.h}.) If the primitive has no upper limit on
>> -the number of Lisp arguments, it must have exactly two C arguments:
>> -the first is the number of Lisp arguments, and the second is the
>> -address of a block containing their values. These have types
>> -@code{int} and @w{@code{Lisp_Object *}} respectively. Since
>> -@code{Lisp_Object} can hold any Lisp object of any data type, you
>> -can determine the actual data type only at run time; so if you want
>> -a primitive to accept only a certain type of argument, you must check
>> -the type explicitly using a suitable predicate (@pxref{Type Predicates}).
>> +in the file @file{lisp.h}.) If the primitive is a special form, it
>> +must accept a Lisp list containing its unevaluated Lisp arguments as a
>> +single argument of type @code{Lisp_Object}. If the primitive has no
>> +upper limit on the number of evaluated Lisp arguments, it must have
>> +exactly two C arguments: the first is the number of Lisp arguments,
>> +and the second is the address of a block containing their values.
>> +These have types @code{ptrdiff_t} and @w{@code{Lisp_Object *}},
>> +respectively. Since @code{Lisp_Object} can hold any Lisp object of
>> +any data type, you can determine the actual data type only at run
>> +time; so if you want a primitive to accept only a certain type of
>> +argument, you must check the type explicitly using a suitable
>> +predicate (@pxref{Type Predicates}).
>> @cindex type checking internals
>
> This part sounds OK to me, and is probably more than enough to fix the
> issue at hand.
Indeed, thanks.
>> - case ON_NOTHING: /* NOT in window at all. */
>> + case ON_NOTHING:
>
> This seems a change for the worst?
I'll bring back the comments.
>> > 2. "Although the garbage collector does not reclaim objects reachable
>> > from C ‘Lisp_Object’ stack variables, it may move non-object
>> > components of an object, such as string contents; so functions
>> > that access non-object components must take care to refetch their
>> > addresses after performing Lisp evaluation."
>> >
>> > I don't think this is very clear. What is non-object components? How
>> > would I refetch their addresses? How is this relevant to the topic at
>> > hand?
>>
>> I don't know about this.
>
> I clarified that.
Thanks,
--
Basil