Add frame identifiers (bug#80138)HEADmaster

A unique frame id is assigned to a new or cloned frame, and
reused on an undeleted frame.

The id facilitates unambiguous identification among frames that
share identical names or titles, deleted frames where a live
frame object no longer exists that we can resurrect by id, for
example via 'tab-bar-undo-close-tab'.  It also aids debugging at
the C level using the frame struct member id.

Rewrite 'clone-frame' and 'undelete-frame' to not let bind
variables that 'make-frame' uses to avoid conflicts with nested
'make-frame' calls, for example via
'after-make-frame-functions'.

* lisp/frame.el (clone-frame, undelete-frame): Use
'frame--purify-parameters' to supply parameters explicitly.
(undelete-frame--save-deleted-frame): Save frame id for
restoration.
(undelete-frame): Restore frame id.
(frame--purify-parameters): New defun.
(make-frame): Assign a new id for a new or cloned frame, reuse
for undeleted frame.
* src/frame.h (struct frame): Add id member.
(frame_next_id): New extern.
* src/frame.c (frame_next_id): New global counter.
(frame_set_id, frame_set_id_from_params): New function.
(Fframe_id): New DEFUN.
(syms_of_frame <Sframe_id>): New defsubr.
(syms_of_frame <Qinternal_id>): New DEFSYM.
(syms_of_frame <frame_internal_parameters>): Add 'Qinternal_id'.
* src/androidfns.c (Fx_create_frame):
* src/haikufns.c (Fx_create_frame):
* src/nsfns.m (Fx_create_frame):
* src/pgtkfns.c (Fx_create_frame):
* src/w32fns.c (Fx_create_frame):
* src/xfns.c (Fx_create_frame): Call 'frame_set_id_from_params'.
* doc/lispref/frames.texi: Add documentation.
* etc/NEWS: Announce frame id.

1 files changed, 82 insertions, 0 deletions

diff --git a/src/frame.c b/src/frame.c
index 5d38f015130..033215a76ec 100644
--- a/src/frame.c
+++ b/src/frame.c
@@ -337,6 +337,83 @@ return values.  */)
           : Qnil);
 }
 
+
+/*                         Frame id.                             */
+
+EMACS_UINT frame_next_id = 1; /* 0 indicates no id (yet) set.  */
+
+DEFUN ("frame-id", Fframe_id, Sframe_id, 0, 1, 0,
+       doc: /* Return FRAME's id.
+If FRAME is nil, use the selected frame.
+Return nil if the id has not been set.  */)
+  (Lisp_Object frame)
+{
+  if (NILP (frame))
+    frame = selected_frame;
+  struct frame *f = decode_live_frame (frame);
+  if (f->id == 0)
+    return Qnil;
+  else
+    return make_fixnum (f->id);
+}
+
+/** frame_set_id: Set frame F's id to ID.
+
+    If ID is 0 and F's ID is 0, use frame_next_id and increment it,
+    otherwise, use ID.
+
+    Signal an error if ID >= frame_next_id.
+    Signal an error if ID is in use on another live frame.
+
+    Return ID if it was used, 0 otherwise.  */
+EMACS_UINT
+frame_set_id (struct frame *f, EMACS_UINT id)
+{
+  if (id >= frame_next_id)
+    error ("Specified frame ID unassigned");
+
+  if (id > 0)
+    {
+      eassume (CONSP (Vframe_list));
+      Lisp_Object frame, tail = Qnil;
+      FOR_EACH_FRAME (tail, frame)
+        {
+          if (id == XFRAME (frame)->id)
+            error ("Specified frame ID already in use");
+        }
+    }
+
+  if (id == 0)
+    if (f->id != 0)
+      return 0;
+    else
+      f->id = frame_next_id++;
+  else
+    f->id = id;
+  return f->id;
+}
+
+/** frame_set_id_from_params: Set frame F's id from params, if present.
+
+    Call frame_set_id to using the frame parameter 'frame-id, if present
+    and a valid positive integer greater than 0, otherwise use 0.
+
+    Return frame_set_id's return value.  */
+EMACS_UINT
+frame_set_id_from_params (struct frame *f, Lisp_Object params)
+{
+  EMACS_UINT id = 0;
+  Lisp_Object param_id = Fcdr (Fassq (Qframe_id, params));
+  if (TYPE_RANGED_FIXNUMP (int, param_id))
+    {
+      EMACS_INT id_1 = XFIXNUM (param_id);
+      if (id_1 > 0)
+        id = (EMACS_UINT) id_1;
+    }
+  return frame_set_id (f, id);
+}
+
+
 DEFUN ("window-system", Fwindow_system, Swindow_system, 0, 1, 0,
        doc: /* The name of the window system that FRAME is displaying through.
 The value is a symbol:
@@ -1358,6 +1435,7 @@ make_initial_frame (void)
 
   f = make_frame (true);
   XSETFRAME (frame, f);
+  frame_set_id (f, 0);
 
   Vframe_list = Fcons (frame, Vframe_list);
 
@@ -1742,6 +1820,7 @@ affects all frames on the same terminal device.  */)
      frames don't obscure other frames.  */
   Lisp_Object parent = Fcdr (Fassq (Qparent_frame, parms));
   struct frame *f = make_terminal_frame (t, parent, parms);
+  frame_set_id_from_params (f, parms);
 
   if (!noninteractive)
     init_frame_faces (f);
@@ -7195,6 +7274,7 @@ syms_of_frame (void)
   DEFSYM (Qfont_parameter, "font-parameter");
   DEFSYM (Qforce, "force");
   DEFSYM (Qinhibit, "inhibit");
+  DEFSYM (Qframe_id, "frame-id");
   DEFSYM (Qcloned_from, "cloned-from");
   DEFSYM (Qundeleted, "undeleted");
 
@@ -7581,6 +7661,7 @@ allow `make-frame' to show the current buffer even if its hidden.  */);
 #else
   frame_internal_parameters = list3 (Qname, Qparent_id, Qwindow_id);
 #endif
+  frame_internal_parameters = Fcons (Qframe_id, frame_internal_parameters);
   frame_internal_parameters = Fcons (Qcloned_from, frame_internal_parameters);
   frame_internal_parameters = Fcons (Qundeleted, frame_internal_parameters);
 
@@ -7607,6 +7688,7 @@ The default is \\+`inhibit' in NS builds and nil everywhere else.  */);
   alter_fullscreen_frames = Qnil;
 #endif
 
+  defsubr (&Sframe_id);
   defsubr (&Sframep);
   defsubr (&Sframe_live_p);
   defsubr (&Swindow_system);