X11::Protocol::GrabServer (3)

Leading comments

Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/X11::Protocol::GrabServer.3pm".)

NAME

X11::Protocol::GrabServer -- object-oriented server grabbing

SYNOPSIS

 use X11::Protocol::GrabServer;
 {
   my $grab = X11::Protocol::GrabServer->new ($X); 
   do_some_things();
   # UngrabServer when $grab destroyed
 }

DESCRIPTION

This is an object-oriented approach to GrabServer / UngrabServer on an "X11::Protocol" connection. A grab object represents a desired server grab and destroying it ungrabs.

The first grab object on a connection does a "GrabServer()" and the last destroyed does an "UngrabServer()". The idea is that it's easier to manage the lifespan of a grabbing object in a block etc than to be sure of catching all exits.

Multiple grab objects can overlap or nest. A single "GrabServer()" is done and it remains until the last object is destroyed. This is good in a library or sub-function where an "UngrabServer()" should wait until the end of any outer desired grab.

A server grab is usually to make a few operations atomic, for instance something global like root window properties. A block-based temporary per the synopsis above is typical. It's also possible to hold a grab object for an extended time, perhaps for some state driven interaction.

Care must be taken not to grab for too long since other client programs are locked out. If a grabbing program hangs then the server will be unusable until the program is killed, or its

etc server connection is broken.

Weak $X

If Perl weak references are available (Perl 5.6 and up and "Scalar::Util" with its usual code), then a grab object holds only a weak reference to the target $X connection. This means the grab doesn't keep the connection up once nothing else is interested. When a connection is destroyed the server ungrabs automatically so there's no need for an explicit "UngrabServer()" in that case.

The main effect of the weakening is that $X can be garbage collected anywhere within a grabbing block, the same as if there was no grab. Without the weakening it would wait until the end of the block. In practice this only rarely makes a difference.

In the future if an "X11::Protocol" connection gets a notion of an explicit close then the intention would be to skip any "UngrabServer()" in that case too, ie. treat a closed connection the same as a weakened away connection.

Currently no attention is paid to whether the server has disconnected the link. A "UngrabServer()" is done on destroy in the usual way. If the server has disconnected then a "SIGPIPE" or "EPIPE" occurs the same as for any other request sent to the $X.

FUNCTIONS

$g = X11::Protocol::GrabServer->new ($X)

$X is an "X11::Protocol" object. Create and return a $g object representing a grab of the $X server.

If this new $g is the first new grab on $X then an "$X->GrabServer" is done.

$g->ungrab ()

Ungrab the $g object. An ungrab is done automatically when $g is destroyed, but "$g->ungrab()" can do it sooner.

If $g is already ungrabbed this way then do nothing.

$g->grab ()

Re-grab with the $g object. This can be used after a "$g->ungrab()" to grab again using the same object, the same as if newly created.

If $g is already grabbing, then do nothing.

$bool = $g->is_grabbed ()

Return true if $g is grabbing. This is true when first created, or false after a "$g->ungrab()".

SEE ALSO

X11::Protocol, X11::Protocol::Other

HOME PAGE

<user42.tuxfamily.org/x11-protocol-other/index.html>

LICENSE

Copyright 2010, 2011, 2012, 2013 Kevin Ryde

X11-Protocol-Other is free software; you can redistribute it and/or modify it under the terms of the

General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

X11-Protocol-Other is distributed in the hope that it will be useful, but

; without even the implied warranty of or See the General Public License for more details.

You should have received a copy of the

General Public License along with X11-Protocol-Other. If not, see <www.gnu.org/licenses>.