components/x11/sun-ext-protos/files/docs/sun-sme.txt

   1 # Copyright (c) 1994, 2007, Oracle and/or its affiliates. All rights reserved.
   2 #
   3 # Permission is hereby granted, free of charge, to any person obtaining a
   4 # copy of this software and associated documentation files (the "Software"),
   5 # to deal in the Software without restriction, including without limitation
   6 # the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 # and/or sell copies of the Software, and to permit persons to whom the
   8 # Software is furnished to do so, subject to the following conditions:
   9 #
  10 # The above copyright notice and this permission notice (including the next
  11 # paragraph) shall be included in all copies or substantial portions of the
  12 # Software.
  13 #
  14 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  17 # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20 # DEALINGS IN THE SOFTWARE.
  21 #
  22 # Originally submitted as PSARC/1994/377
  23
  24 The purpose of this document is to fast track the implementation of a
  25 shared memory based transport mechanism for the OpenWindows server
  26 and clients. This document briefly describes some of the design
  27 and implementation features of this mechanism. Section 3, entitled
  28 "User Interface for SUN_SME", describes the user visible interface.
  29 We are requesting that the interface in Section 3 be declared a Public
  30 interface.  The components that have been affected by SUN_SME are Xsun
  31 and libX11.
  32
  33 It should be noted that SUN_SME is targeted at improving benchmark
  34 performance. The current implementation uses SYSV shared memory and
  35 thus has a limit of 6 shared memory connections.  Once the limit is
  36 exceeded the implementation silently falls back to a pipe connection.
  37 The plan is to eventually remove this limitation by using SunOS native
  38 shared memory mechanisms.
  39
  40 1. What is 'SHARED_MEMORY_EXTENSION'(SUN_SME) ?
  41
  42         SUN_SME is an extension to the OpenWindows server with the purpose
  43         allowing clients to send requests to the server via shared memory.
  44         SUN_SME is intended to be another form of local transport mechanism
  45         like Unix sockets and the pipes mechanisms. The SUN_SME extension
  46         will be versioned so that changes can be made in a compatible manner
  47         if they become necessary.
  48
  49 2. How and where 'SUN_SME' gets used ?
  50
  51         In order for a client to communicate via shared memory with the
  52         server it should have its display environment variable set to
  53         :x.y (where x is the display number and y is the screen
  54         number) and the environment variable XSUNTRANSPORT set to
  55         "shmem" before it is started. If the display variable is set
  56         to :x.y and XSUNTRANSPORT set to "shmem", local clients query
  57         the X server for the SUN_SME Extension and if it is supported
  58         the connection is set up.
  59
  60         It should be noted that shared memory will be used for sending
  61         requests from client to server only. Replies/events and all
  62         other communication initiated by the X server will use the
  63         default IPC mechanism which is pipes in OW 3.4. Also, one shared
  64         memory segment will be set up per display connection.
  65
  66 3. User Interface for SUN_SME
  67
  68         The user interface for SUN_SME will be documented in the man
  69         pages and other appropriate documentation.  Following, are the
  70         visible changes that have been introduced by SUN_SME :
  71
  72                 - If the value of DISPLAY has any form other than
  73                   :x[.y], the transport is determined directly from
  74                   its value (using the standard, pre-existent X rules).
  75                   Otherwise, the value of XSUNTRANSPORT becomes relevant.
  76                   If unset, a suitable (but otherwise unspecified) local
  77                   transport is used; otherwise, the transport named by
  78                   its value is used, if available.  In the case of shared
  79                   memory, XSUNTRANSPORT must be set to "shmem".
  80
  81                 - The size of the shared memory segment between the
  82                   client and server will be user configurable by setting
  83                   the environment variable XSUNSMESIZE. The default value
  84                   for XSUNSMESIZE will be 64K.
  85
  86                 - The xdpyinfo client will return SUN_SME in the list
  87                   of supported extensions.  Similarly the XQueryExtension()
  88                   and XListExtensions() routines in Xlib and the corresponding
  89                   QueryExtension and ListExtensions X protocol requests will
  90                   indicate the existence of the SUN_SME extension.  However,
  91                   this information is not particularly useful to users or
  92                   application developers, since the extension interfaces
  93                   are intended to be Consolidation Private.
  94
  95 4. Implementation Features
  96
  97 This section is for information purposes only, since the extension
  98 interfaces are Consolidation Private.  The affected components are
  99 libX11 and Xsun.
 100
 101 Currently clients communicate with the server via pipes and sockets
 102 (TCP and UDP). Our goal is to provide a shared memory communication
 103 mechanism between the client and the server. Communicating via
 104 shared memory has been measured to be more efficient than sockets/pipes.
 105 The current SUN_SME implementation uses SYSV shared memory.  The
 106 final implementation will use SunOS shared memory.
 107
 108 Some characteristics of this mechanism are :
 109
 110         - Shared memory will be only be used for client requests.
 111         Replies from the server will be sent via pipes.
 112
 113         - The size of the shared memory segment will be set to 64K by
 114         default. This size will be use configurable via the XSUNSMESIZE
 115         environment variable.
 116
 117         - Variable size buffers are allocated out of the shared memory
 118         segment in a ring-like fashion. The buffers in the shared memory
 119         segment are indexed with the index containing the address
 120         and size of the buffers. The client updates the head pointer
 121         every time a request buffer is inserted and the server
 122         updates the tail pointer every time a request buffer is processed.
 123
 124         - Requests sent by the client are packetized and sent in a
 125         buffer instead of sending one request per buffer using the
 126         same algorithm used by pipe and socket connections. The client
 127         sends a byte through the pipe to the server indicating
 128         that a request buffer has been sent. This way the server
 129         has something to poll on and the traditional select mechanism
 130         can be retained.
 131
 132         - Suitable locking mechanisms will be used to insure consistency
 133         of shared memory between client and server under the PSO memory
 134         model when/if it becomes possible for user processes to run under
 135         PSO.
 136
 137         - If the client runs out of request buffers it gets blocked and
 138         waits for a special reply denoted by SMEREPLY.
 139
 140         - Large requests (for e.g. XPutImage) are split into multiple
 141         requests.
 142
 143         - In the event that the maximum allowable shared memory has
 144         been allocated and a client attempts to initiate a shared
 145         memory connection, the transport mechanism will default
 146         to pipes.
 147
 148
 149
 150
 151