Re: Session management patch, please comment.

[Jan D.]

Richard Stallman wrote:
> It is an amazingly large amount of code, but I suppose there is no
> easier way.  What a pity.

Yes, the use of callbacks for everything makes it look larger than it is.

> Did you copy any substantial part of it from the X distribution, or
> anywhere else?  Or did you write all of it afresh?

It is all my code from scratch. I wanted to do it all afresh to get a 
better understanding of X session management. I just used the specification.

>     + DEFUN ("x-sm-interact-done", Fx_sm_interact_done, Sx_sm_interact_done, 1, 
> 1, 0,
>     +        doc: /* End interaction as a response to save_yourself.
>     + If the argument CANCEL is non-nil, Emacs will tell the session manager
>     + to cancel the shutdown */)
>
> This isn't clear enough--it doesn't tell me when to use this function
> or how.  Perhaps it would be clear to a person who knows this relates
> to the session manager *and* knows all about the session manager, but
> that is not good enough; this doc string ought to make sense to an
> ordinary Emacs Lisp programmer who knows nothing about the session
> manager.

Well, actually I didn't even want this function, but I could not find 
another way to call C from lisp.  It is not meant to be "external", 
rather a link between the C part and the lisp part of the session 
management code.  But I don't think lisp has some kind of "private" 
functions, or?

I'll try to explain.

The session manager sends Emacs a save_yourself message telling Emacs 
that the window system is shutting down.

Emacs then requests from the session manager that it would like to 
interact with its user (i.e. pop up windows and such).  The session 
manager replies that that is OK.  In response the session manager wants 
a interact_done when interaction is done.

Emacs is executing C code when this happens.  To get into lisp code, a 
save-yourself-event is generated and the lisp function bound to the 
event executes (handle-save-yourself).

handle-save-yourself then executes functions in the save-yourself-hook 
and by calling x-sm-interact-done it finally informs the C code that it 
shall send the interaction-done message to the session manager.


Ideally, (as I am a C/C++/Java kind of person) I would like 
save-yourself-event, handle-save-yourself and x-sm-interact-done to be 
"private" so that users can't override any part of the chain they form 
(the thought of that happening makes me a bit uneasy).

If there is a way to make that happen, I'd be glad to know.  If not, how 
about this documentation:

"End interaction as a response to save_yourself.
A session manager can tell Emacs that the window system is shutting down 
by sending Emacs a save_yourself message.  Emacs then executes functions 
in `save-yourself-hook'.  After that, this function shall be called to 
inform the session manager that it can continue or abort shutting down 
the window system.

If the argument CANCEL is non-nil, Emacs will tell the session manager 
to cancel the shutdown."


>     +     doc: /* The previous session id Emacs got from session manager.
>     + This is nil if Emacs was not started by the session manager.
>     + The value of this variable and `x-sm-id' may be the same, depending on how
>     + the session manager works.
>     + See also `x-sm-id'.*/);
>
> This doc string should explain what the previous session id is good
> for.  What does it mean?  Documentation for data should explain its
> overall meaning, not just what it looks like and what values are found
> when.

How about this (a bit long perhaps):

"The previous session id Emacs got from session manager.
If Emacs is running on a window system that has a session manager, the 
session manager gives Emacs a session id.  It is feasible for Emacs lisp 
code to use the session id to save configuration in, for example, a file 
with a file name based on the session id.  If Emacs is running when the 
window system is shut down, the session manager remembers that Emacs was 
running and saves the session id Emacs had.

When the window system is started again, the session manager restarts 
Emacs and hands Emacs the session id it had the last time it was 
running.  This is now the previous session id and the value of this 
variable.  If configuration was saved in a file as stated above, the 
previous session id shall be used to reconstruct the file name.

The session id Emacs has while it is running is in the variable 
`x-sm-id'.  The value of this variable and `x-sm-id' may be the same, 
depending on how the session manager works.

See also `save-yourself-hook'."

>     +   DEFVAR_LISP ("x-sm-cancel-shutdown", &Vx_sm_cancel_shutdown,
>     +     doc: /* If non-nil, Emacs will cancel the session manager shutdown.
>     + Setting this variable enables hooks in `save-yourself-hook' to cancel
>     + a shutdown.  This should only be done at an explicit user request to do
>     + so.*/);
>
> When should the Lisp programmer set or use this?  When is it tested?
> I don't see anything in the code that ever tests this variable, so I
> am at a loss to understand its purpose.

In the lisp function handle-save-yourself, it is used as an argument to 
x-sm-interact-done.

The idea was that as functions in save-yourself-hook are executing, they 
might interact with the user, for instance pop up a dialog.  That dialog 
can have the possibility to cancel the whole window system shutdown.  If 
the lisp code wants to do that, it shall set this variable to something 
non-nil.

>     + (defvar save-yourself-hook nil
>     +   "Hooks run when a save-yourself event occurs.
>     + The hook gets one argument, the current session id.  This is a string and
>     + can for example, be used to create a unique file name.")
>
> Since this is not a normal hook, it should have a different name.
> Perhaps save-yourself-functions.  But I think save-session-functions
> is a clearer name; it gives the user more information and is more
> natural.
>
>     + (defvar restart-yourself-hook nil
>     +   "Hooks run when Emacs is started by a session manager..
>     + The hook gets two arguments, PREV-SESSID and SESSID.
>
> Likewise this.  Perhaps restart-session-functions.
>
> In general, replacing "yourself" with "session" in all the function and 
> variable names would be an improvement.

Yes, this is a good idea, I just used the names in the SM specification 
without much thought.

        Jan D.