doc/scwmexec.proto

   1
   2 A brief description of the scwmexec protocol
   3
   4 * The scwmexec protocol on a particular X screen involves one server
   5 and one or more clients. The following steps are involved in
   6 negotiating the protocol:
   7
   8 0) On startup, the server advertises availability of the scwmexec
   9 protocol on a given screen by setting the "SCWMEXEC_LISTENER" property
  10 on the root window. It then waits for clients to initiate transactions
  11 by setting the SCWMEXEC_REQWIN property on the root window.
  12
  13 1) Clients use a dedicated window for the transaction. An ordinary app
  14 window may be used, however, the library code creates a separate
  15 window for simplicities sake. The client first sets the
  16 SCWMEXEC_REQUEST property on the window with the command language
  17 expression it would like to have evaluated.
  18
  19 2) Then it sets the SCWMEXEC_REQWIN propert on the root window to the
  20 32 bit window ID of the window that has the request, and listens for
  21 property changes
  22
  23 3) The server, upon being notified of the SCWMEXEC_REQWIN change,
  24 determines the window that is making the request and deletes the
  25 SCWMEXEC_REQWIN property.
  26
  27 4) The server reads the SCWMEXEC_REQUEST property on the request
  28 window, deleting it in the process.
  29
  30 5) The server evaluates this expression and sets the SCWMEXEC_REPLY
  31 property on the client window to a string representation of the
  32 result.
  33
  34 6) The client, upon notification of the SCWMEXEC_REPLY change, reads
  35 the reply, delting it in the process.
  36
  37 Note that a given client is only allowed to have one active request at
  38 a time to avoid races.
  39
  40
  41 Possible extensions:
  42
  43 * Set SCWMEXEC_REQWIN property in append mode, and have the server
  44 serve all requests it finds in the property on a PropertyNotify before
  45 deleting the property. This should make the protocol 100% safe against
  46 race conditions.
  47
  48 * PropertyNotify events are delievered for all property changes to
  49 clients that listen to them; this means that if separate windows are
  50 used, the SCWMEXEC_REQWIN step of the protocol may be unnecessary; the
  51 server can just handle SCWMEXEC_REQUEST property changes on all
  52 windows. Any good reason not to do this? Would also solve the race
  53 issue.
  54
  55 * Error reporting: If evaluating the expression results in an error,
  56 the server should not set SCWMEXEC_REPLY on the request window, but
  57 rather SCWMEXEC_ERROR, which should contain an appropriate error
  58 string.
  59
  60 * Output redirection: Cake, just set SCWMEXEC_OUTPUT in addition to
  61 SCWMEXEC_REPLY or _ERROR.
  62
  63 * Input redirection: This one is tricky, the server would have to
  64 request further input from the client in the middle of handling a
  65 request, this would require hacking the lib a lot.
  66
  67 * Suppress printing of unspecified values: this could be solved in the
  68 client, but this is not 100% robust; both the unspecified value and
  69 '#{#<unspecified>}# print as #<unspecified> in guile. OTOH, do we
  70 really care? In any case, some notification mechanism could be used.
  71
  72 * Use of ClientMessages: use ClientMessage events to send the server
  73 reply to the client client, it should be easier to filter these out
  74 for a specific window than property notifications. This should solve
  75 the eating of PropertyNotify problem below. But can arbitrary-length
  76 strings easily be sent through ClientMessages? (Answer: no, but you
  77 could just set the properties and use the ClientMessage to notify the
  78 client that they are ready).
  79
  80 * Provide a gdk/gtk version of the scwmexec library, allowing
  81 notification to be implemented through signals and thus not hosing the
  82 event loop. This should make asynchronous operation of the protocol a
  83 piece of cake for gtk-based graphical apps.
  84
  85 * Maybe versions for other toolkits too.
  86
  87
  88
  89 Caveats:
  90
  91 * The scwmexec library code may block indefinitely. Solution: a
  92 timeout should be added. However, since scwm operations may take
  93 indefinitely long, it may be useful for some clients to keep running
  94 their UI while waiting for a result. Solutions too this include
  95 threads or integrating the protocol into the client event loop.
  96
  97 * The library code will also eat all PropertyNotify events while
  98 waiting for the server reply. This is bad for programs that otherwise
  99 use X11. Solutions include integrating scwmexec protocol management
 100 into the app's event loop, oor using a separate connection to the
 101 display to use the scwmexec protocol.