The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Emacs::EPL - Protocol implementation and data conversions for Emacs Perl

SYNOPSIS

    use Emacs::EPL ':server';
    Emacs::EPL::loop;

DESCRIPTION

This module is used internally by epl.el and Emacs::Lisp.

If you use eval to catch errors in Lisp functions, and $@ contains a string beginning with '.Emacs::EPL' (note initial dot), be sure to die with the same string before returning control to Lisp.

Protocol State Transition Table

This stuff is mainly for the benefit of the author.

    NO.   CONSTRAINTS            INITIAL       MSG CLASS    FINAL
    ----- ---------------------- ------------- ------------ --------------
    (1)                          <0>           START        <1>
    (2)                          <1>           RAISE        <0>
    (3)                          <1>           RETURN       <2,0>
    (4)                          <2,0>         RETURN       <0>
    (5)                          <2,n>         UNREF        <3,0,n>
    (6)                          <2,n>         CALL         <2,n+1>
    (7)   n>0                    <2,n>         RETURN       <2,n-1>
    (13)                         <3,0,n>       RETURN       <2,n>
    (14)                         <3,m,n>       UNREF        <3,m+1,n>
    (15)  m>0                    <3,m,n>       RETURN       <3,m-1,n>

The master is defined to be the process that sends the START message. The other process is the slave. It follows by induction from the table that the master sends in states <0>, <2,n> for even n, and <3,m,n> for odd m+n, and that the slave sends in all other states.

Message Classes

START

Initiate communication, e.g. by running a subprocess or opening a connection. The slave, if able, sends either a handshake (RETURN) or an exception (RAISE) in response. If an exception is raised, no further communication is permitted.

 frame = 1
CALL

Request to run code. The calling process may be reentered by a subsequent CALL. Our call ends when we receive a RETURN, RAISE, or POP in the same frame or we send a POP in a next inner frame. If we receive a POP and subsequently use RETURN to exit this frame, the value we return will be ignored.

 frame += 1
 Lisp: funcall
 Perl: eval
RETURN

Deliver the response to a CALL request (7), report successful startup (3), or mark the end of a series of UNREF requests (13, 15). Not permitted in a popped frame.

The three meanings could have been given different names: ``return'', ``handshake'', and ``end_unrefs''.

 frame -= 1
 Lisp: function return
 Perl: eval return
RAISE

Return via exception mechanism, i.e., non-locally. RAISE has the same protocol semantics as RETURN, except that it is permitted in popped frames. It is expected that unless the user has taken specific steps (i.e., a "try" block) in the frame being returned to, the recipient will propagate the exception by sending another RAISE with the same or equivalent argument.

 frame -= 1
 Lisp: signal
 Perl: die
POP

Either terminate communication (4), or exit the current frame (11, 12). This also says that we will ignore the argument of a subsequent RETURN from this frame (but will not ignore a RAISE value).

 frame -= 1
 Lisp: throw, kill-emacs
 Perl: exit, any nonlocal jump other than die
UNREF

Send a list of handles that they have given us and that we promise never to use again, so that they may free up some resources. Maybe the resources they free will include references to our stuff, so they may send us some UNREF requests before ending the list with a RETURN. They must not, however, issue any other kinds of requests until they've sent RETURN in this frame.

 frame += 1
 Lisp: perl-free-ref, whatever garbage-detection means is in effect
 Perl: DESTROY

Thoughts

Mark-and-sweep garbage collection could be supported by:

    (16)                         <2,n,@s>      GC           <4,n,@s>
    (17)                         <4,n,@s>      RETURN(0)    <2,n,@s>
    (18)                         <4,n,@s>      RETURN(1)    <5,0,n,@s>
    (19)                         <5,0,n,@s>    RETURN       <3,0,n,@s>
    (20)                         <5,m,n,@s>    MARK         <5,m+1,n,@s>
    (21)  m>=1                   <5,m,n,@s>    RETURN       <5,m-1,n,@s>

Transition (17) gives the receiver a chance to refuse to support mark-and-sweep or simply to indicate that all references are in use. Which of these two is the case could be indicated by another return code.

It might be useful to distinguish between recursive and nonrecursive calls:

    (22)                         <2,n>         SIMPLE_CALL  <6,n>
    (23)                         <6,n>         RETURN       <2,n>

Further state classes could be introduced to allow UNREF, GC, RAISE, or POP operations during nonrecursive calls. Better yet, add some boolean parameters to the states we've got and to CALL.

Hey, how about CALL/CC and START_THREAD. Then of course you'd need JOIN, YIELD, LOCK, WAIT, ... . Pretty soon you'd have yourself an operating system. Yawn.

The current EPL implementation uses only transitions of types (1) to (15).

COPYRIGHT

Copyright (C) 2001 by John Tobey, jtobey@john-edwin-tobey.org. All rights reserved.

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; see the file COPYING.  If not, write to the
  Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
  MA 02111-1307  USA

SEE ALSO

Emacs::Lisp, Emacs.