gnu.x11
Class Connection

java.lang.Object
  extended by gnu.x11.Connection

public class Connection
extends java.lang.Object

Low-level network input/output with X server.

Flow Control and Concurrency

From X11 protocol specification:

Whenever the server is writing to a given connection, it is permissible for the server to stop reading from that connection (but if the writing would block, it must continue to service other connections). The server is not required to buffer more than a single request per connection at one time. For a given connection to the server, a client can block while reading from the connection but should undertake to read (events and errors) when writing would block. Failure on the part of a client to obey this rule could result in a deadlocked connection, although deadlock is probably unlikely unless either the transport layer has very little buffering or the client attempts to send large numbers of requests without ever reading replies or checking for errors and events.

Whether or not a server is implemented with internal concurrency, the overall effect must be as if individual requests are executed to completion in some serial order, and requests from a given connection must be executed in delivery order (that is, the total execution order is a shuffle of the individual streams). The execution of a request includes validating all arguments, collecting all data for any reply, and generating and queueing all required events. However, it does not include the actual transmission of the reply and the events. In addition, the effect of any other cause that can generate multiple events (for example, activation of a grab or pointer motion) must effectively generate and queue all required events indivisibly with respect to all other causes and requests. For a request from a given client, any events destined for that client that are caused by executing the request must be sent to the client before any reply or error is sent.


Field Summary
static int ASYNCHRONOUS
          In this mode, protocol requests are sent asynchronously to X server.
 java.io.DataInputStream din
           
 Display display
           
 int display_no
           
 java.util.Vector events
           
 java.lang.String hostname
           
static int MAX_REUQEST_COUNT
           
 int next_seq_no
          Request sequence number counter.
 java.io.OutputStream out
           
 java.lang.Object read_lock
           
 boolean reading_reply
           
 int request_count
           
 Request[] requests
           
static int ROUND_TRIP
          In this mode, protocol requests are sent synchronously to X server, and X server is deliberately forced to give a round-trip reply.
 Data saved_reply
           
 int send_mode
          valid: ASYNCHRONOUS (default), SYNCHRONOUS, ROUND_TRIP
static java.lang.String[] SEND_MODE_STRINGS
           
 java.net.Socket socket
           
static int SYNCHRONOUS
          In this mode, protocol requests are sent synchronously to X server.
 
Constructor Summary
Connection(Display display, java.lang.String hostname, int display_no)
           
 
Method Summary
 void check_error()
           
 void close()
          Flush all queued requests and close network connection.
 boolean enqueue_request(Request request)
           
 void flush()
           
 java.util.Vector pull_all_events()
          Pull all events on network.
 Event read_event(boolean blocking, boolean remove)
           
 Data read_message(boolean blocking)
           
 Data read_reply(Request request)
           
 int send(Request request, boolean round_trip)
           
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

display

public Display display

display_no

public int display_no

hostname

public java.lang.String hostname

socket

public java.net.Socket socket

din

public java.io.DataInputStream din

read_lock

public java.lang.Object read_lock

reading_reply

public boolean reading_reply

saved_reply

public Data saved_reply

events

public java.util.Vector events

send_mode

public int send_mode
valid: ASYNCHRONOUS (default), SYNCHRONOUS, ROUND_TRIP


SEND_MODE_STRINGS

public static final java.lang.String[] SEND_MODE_STRINGS

ASYNCHRONOUS

public static final int ASYNCHRONOUS
In this mode, protocol requests are sent asynchronously to X server. This is the default mode for C xlib as well. It means that protocol requests will be queued and aggregated if possible, and then send to X server in a burst only when necessary (reading reply for round-trip request, reading event, or explicit flush). This mode offers the highest performance over slow network connections.

See Also:
Constant Field Values

SYNCHRONOUS

public static final int SYNCHRONOUS
In this mode, protocol requests are sent synchronously to X server. It means that protocol requests are sent to the network laywer as soon as the function is called. This mode may aid debugging network or library problems but it hurts the performance.

See Also:
Constant Field Values

ROUND_TRIP

public static final int ROUND_TRIP
In this mode, protocol requests are sent synchronously to X server, and X server is deliberately forced to give a round-trip reply. It means that if the request is a one-way request (XCreateWindow), an additional dummy round-trip request will be sent to X server to force X server to give a reply immediately; and that if the request is already a round-trip request (XGetGeometry), there will be no additional dummy round-trip request. This mode significantly hurts the performance but offers good debugging tracebacks. Because any error will be reported by X server at the point of function call, a correct stack trace will show where the problem is in the code.

See Also:
Constant Field Values

MAX_REUQEST_COUNT

public static final int MAX_REUQEST_COUNT
See Also:
Constant Field Values

request_count

public int request_count

requests

public Request[] requests

out

public java.io.OutputStream out

next_seq_no

public int next_seq_no
Request sequence number counter.

From Protocol Specification: Every request on a given connection is implicitly assigned a sequence number, starting with one, that is used in replies, errors, and events.

Constructor Detail

Connection

public Connection(Display display,
                  java.lang.String hostname,
                  int display_no)
Method Detail

check_error

public void check_error()

close

public void close()
Flush all queued requests and close network connection.

See Also:
XCloseDisplay, flush()

enqueue_request

public boolean enqueue_request(Request request)

flush

public void flush()

pull_all_events

public java.util.Vector pull_all_events()
Pull all events on network. Caution: This pulls all events that X server has already put on network, not necessarily all events that X server schedules for this client. You must use grabbing server technique as follows (used in Puppet.read_and_dispatch_event() as well) to pull all events on server.
   display.grab_server ();
 
   display.check_error ();
   Vector all_and_everything = pull_all_events ();
 
   display.grab_server ();
 
Note display.check_error () forces a round-trip reply from X server, and X server would flush pending all events before that reply.


read_event

public Event read_event(boolean blocking,
                        boolean remove)

read_message

public Data read_message(boolean blocking)

read_reply

public Data read_reply(Request request)

send

public int send(Request request,
                boolean round_trip)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object