GNU bug report logs - #36392
(info "(elisp)Writing Emacs Primitives") might need some clarifications

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 36392 in the body.
You can then email your comments to 36392 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: (info "(elisp)Writing Emacs Primitives") might need some
 clarifications
Date: Wed, 26 Jun 2019 13:31:06 +0200

As a beginner on Emacs Internals, I've been reading:

(info "(elisp)Writing Emacs Primitives")

I hope that you find the following observations useful:

1.  "If the primitive accepts a fixed maximum number of Lisp
    arguments, there must be one C argument for each Lisp argument,
    and each argument must be of type ‘Lisp_Object’.  ...  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."

The example given is DEFUN( "or", ...)

This function has no upper limit on the number of Lisp arguments, but
still has only ONE argument.  Unless I'm missing something, this
contradicts the statement above that "it must have exactly TWO C
arguments" (my emphasis).

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 suggest that the above two points are clarified in the manual
somehow.

Thanks,
Stefan Kangas

Message #8 received at 36392 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 36392 <at> debbugs.gnu.org
Subject: Re: bug#36392: (info "(elisp)Writing Emacs Primitives") might need
 some clarifications
Date: Wed, 26 Jun 2019 14:09:03 +0100

[Message part 1 (text/plain, inline)]

tags 36392 + patch
severity 36392 minor
quit

[0001-Clarify-update-elisp-Writing-Emacs-Primitives.patch (text/x-diff, attachment)]

[Message part 3 (text/plain, inline)]

Stefan Kangas <stefan <at> marxist.se> writes:

> As a beginner on Emacs Internals, I've been reading:
>
> (info "(elisp)Writing Emacs Primitives")
>
> I hope that you find the following observations useful:
>
> 1.  "If the primitive accepts a fixed maximum number of Lisp
>     arguments, there must be one C argument for each Lisp argument,
>     and each argument must be of type ‘Lisp_Object’.  ...  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."
>
> The example given is DEFUN( "or", ...)
>
> This function has no upper limit on the number of Lisp arguments, but
> still has only ONE argument.  Unless I'm missing something, this
> contradicts the statement above that "it must have exactly TWO C
> arguments" (my emphasis).

Indeed, this is because For is a special form (with UNEVALLED args).
Compare it with the definition for Fapply (with MANY args) in the same
file, and see the macros DEFUN_ARGS_UNEVALLED and DEFUN_ARGS_MANY in
lisp.h.

Does the attached patch, suitable for either master or emacs-26, help
clarify this?

> 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.

Thanks,

-- 
Basil

Message #15 received at 36392 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 36392 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#36392: (info "(elisp)Writing Emacs Primitives") might need
 some clarifications
Date: Wed, 26 Jun 2019 18:14:20 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Date: Wed, 26 Jun 2019 14:09:03 +0100
> Cc: 36392 <at> debbugs.gnu.org
> 
> >From 3d85d73858fe0c126277d04db8b99eeb9f09d672 Mon Sep 17 00:00:00 2001
> From: "Basil L. Contovounesios" <contovob <at> 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.

> @@ -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.

> -    case ON_NOTHING:            /* NOT in window at all.  */
> +    case ON_NOTHING:

This seems a change for the worst?

> > 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.

Message #18 received at 36392 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36392 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#36392: (info "(elisp)Writing Emacs Primitives") might need
 some clarifications
Date: Wed, 26 Jun 2019 19:20:25 +0100

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Date: Wed, 26 Jun 2019 14:09:03 +0100
>> Cc: 36392 <at> debbugs.gnu.org
>> 
>> >From 3d85d73858fe0c126277d04db8b99eeb9f09d672 Mon Sep 17 00:00:00 2001
>> From: "Basil L. Contovounesios" <contovob <at> 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

Message #21 received at 36392 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: 36392 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#36392: (info "(elisp)Writing Emacs Primitives") might need
 some clarifications
Date: Wed, 26 Jun 2019 21:34:12 +0300

> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
> Cc: stefan <at> marxist.se,  36392 <at> debbugs.gnu.org
> Date: Wed, 26 Jun 2019 19:20:25 +0100
> 
> Do you prefer not to switch the example to Fwhile?

Yes, I think we should just describe UNEVAL, so that the example
doesn't confuse.

Thanks.

Message #28 received at 36392-done <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 36392-done <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#36392: (info "(elisp)Writing Emacs Primitives") might need
 some clarifications
Date: Wed, 26 Jun 2019 22:29:13 +0100

tags 36392 fixed
close 36392 26.3
quit

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
>> Cc: stefan <at> marxist.se,  36392 <at> debbugs.gnu.org
>> Date: Wed, 26 Jun 2019 19:20:25 +0100
>> 
>> Do you prefer not to switch the example to Fwhile?
>
> Yes, I think we should just describe UNEVAL, so that the example
> doesn't confuse.

Okay, I pushed a more measured patch to emacs-26[1].  Stefan, do these
patches address your concerns, or do you think further clarification is
required?

[1: 8b775c30ad]: Clarify & update (elisp) Writing Emacs Primitives
  2019-06-26 22:16:52 +0100
  https://git.savannah.gnu.org/cgit/emacs.git/commit/?id=8b775c30adaad63a4838e911d6c02e55a4269c4e

Thanks,

-- 
Basil

Message #31 received at 36392 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: "Basil L. Contovounesios" <contovob <at> tcd.ie>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 36392 <at> debbugs.gnu.org
Subject: Re: bug#36392: (info "(elisp)Writing Emacs Primitives") might need
 some clarifications
Date: Thu, 27 Jun 2019 03:01:59 +0200

Basil L. Contovounesios <contovob <at> tcd.ie> writes:
> [...] Stefan, do these
> patches address your concerns, or do you think further clarification is
> required?

Absolutely, these changes makes things much clearer.  Thank you both
for fixing this so promptly.

Best regards,
Stefan Kangas

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.