# Copyright (c) 1994, 2007, Oracle and/or its affiliates. All rights reserved.
#
# Permission is hereby granted, free of charge, to any person obtaining a
# copy of this software and associated documentation files (the "Software"),
# to deal in the Software without restriction, including without limitation
# the rights to use, copy, modify, merge, publish, distribute, sublicense,
# and/or sell copies of the Software, and to permit persons to whom the
# Software is furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice (including the next
# paragraph) shall be included in all copies or substantial portions of the
# Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.
#
# Originally submitted as PSARC/1994/377
The purpose of this document is to fast track the implementation of a
shared memory based transport mechanism for the OpenWindows server
and clients. This document briefly describes some of the design
and implementation features of this mechanism. Section 3, entitled
"User Interface for SUN_SME", describes the user visible interface.
We are requesting that the interface in Section 3 be declared a Public
interface. The components that have been affected by SUN_SME are Xsun
and libX11.
It should be noted that SUN_SME is targeted at improving benchmark
performance. The current implementation uses SYSV shared memory and
thus has a limit of 6 shared memory connections. Once the limit is
exceeded the implementation silently falls back to a pipe connection.
The plan is to eventually remove this limitation by using SunOS native
shared memory mechanisms.
1. What is 'SHARED_MEMORY_EXTENSION'(SUN_SME) ?
SUN_SME is an extension to the OpenWindows server with the purpose
allowing clients to send requests to the server via shared memory.
SUN_SME is intended to be another form of local transport mechanism
like Unix sockets and the pipes mechanisms. The SUN_SME extension
will be versioned so that changes can be made in a compatible manner
if they become necessary.
2. How and where 'SUN_SME' gets used ?
In order for a client to communicate via shared memory with the
server it should have its display environment variable set to
:x.y (where x is the display number and y is the screen
number) and the environment variable XSUNTRANSPORT set to
"shmem" before it is started. If the display variable is set
to :x.y and XSUNTRANSPORT set to "shmem", local clients query
the X server for the SUN_SME Extension and if it is supported
the connection is set up.
It should be noted that shared memory will be used for sending
requests from client to server only. Replies/events and all
other communication initiated by the X server will use the
default IPC mechanism which is pipes in OW 3.4. Also, one shared
memory segment will be set up per display connection.
3. User Interface for SUN_SME
The user interface for SUN_SME will be documented in the man
pages and other appropriate documentation. Following, are the
visible changes that have been introduced by SUN_SME :
- If the value of DISPLAY has any form other than
:x[.y], the transport is determined directly from
its value (using the standard, pre-existent X rules).
Otherwise, the value of XSUNTRANSPORT becomes relevant.
If unset, a suitable (but otherwise unspecified) local
transport is used; otherwise, the transport named by
its value is used, if available. In the case of shared
memory, XSUNTRANSPORT must be set to "shmem".
- The size of the shared memory segment between the
client and server will be user configurable by setting
the environment variable XSUNSMESIZE. The default value
for XSUNSMESIZE will be 64K.
- The xdpyinfo client will return SUN_SME in the list
of supported extensions. Similarly the XQueryExtension()
and XListExtensions() routines in Xlib and the corresponding
QueryExtension and ListExtensions X protocol requests will
indicate the existence of the SUN_SME extension. However,
this information is not particularly useful to users or
application developers, since the extension interfaces
are intended to be Consolidation Private.
4. Implementation Features
This section is for information purposes only, since the extension
interfaces are Consolidation Private. The affected components are
libX11 and Xsun.
Currently clients communicate with the server via pipes and sockets
(TCP and UDP). Our goal is to provide a shared memory communication
mechanism between the client and the server. Communicating via
shared memory has been measured to be more efficient than sockets/pipes.
The current SUN_SME implementation uses SYSV shared memory. The
final implementation will use SunOS shared memory.
Some characteristics of this mechanism are :
- Shared memory will be only be used for client requests.
Replies from the server will be sent via pipes.
- The size of the shared memory segment will be set to 64K by
default. This size will be use configurable via the XSUNSMESIZE
environment variable.
- Variable size buffers are allocated out of the shared memory
segment in a ring-like fashion. The buffers in the shared memory
segment are indexed with the index containing the address
and size of the buffers. The client updates the head pointer
every time a request buffer is inserted and the server
updates the tail pointer every time a request buffer is processed.
- Requests sent by the client are packetized and sent in a
buffer instead of sending one request per buffer using the
same algorithm used by pipe and socket connections. The client
sends a byte through the pipe to the server indicating
that a request buffer has been sent. This way the server
has something to poll on and the traditional select mechanism
can be retained.
- Suitable locking mechanisms will be used to insure consistency
of shared memory between client and server under the PSO memory
model when/if it becomes possible for user processes to run under
PSO.
- If the client runs out of request buffers it gets blocked and
waits for a special reply denoted by SMEREPLY.
- Large requests (for e.g. XPutImage) are split into multiple
requests.
- In the event that the maximum allowable shared memory has
been allocated and a client attempts to initiate a shared
memory connection, the transport mechanism will default
to pipes.