X11::Protocol::GrabServer(3pm)

1X11::Protocol::GrabServUesre(r3)Contributed Perl DocumenXt1a1t:i:oPnrotocol::GrabServer(3)
2
3
4

NAME

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

SYNOPSIS

9        use X11::Protocol::GrabServer;
10        {
11          my $grab = X11::Protocol::GrabServer->new ($X);
12          do_some_things();
13          # UngrabServer when $grab destroyed
14        }
15

DESCRIPTION

17       This is an object-oriented approach to GrabServer / UngrabServer on an
18       "X11::Protocol" connection.  A grab object represents a desired server
19       grab and destroying it ungrabs.
20
21       The first grab object on a connection does a "GrabServer()" and the
22       last destroyed does an "UngrabServer()".  The idea is that it's easier
23       to manage the lifespan of a grabbing object in a block etc than to be
24       sure of catching all exits.
25
26       Multiple grab objects can overlap or nest.  A single "GrabServer()" is
27       done and it remains until the last object is destroyed.  This is good
28       in a library or sub-function where an "UngrabServer()" should wait
29       until the end of outermost desired grab.
30
31       A server grab is usually to make a few operations atomic, for instance
32       something global like root window properties.  A block-based temporary
33       object like the synopsis above is typical.  It's also possible to hold
34       a grab object for an extended time, perhaps for some state driven
35       interaction with the server.
36
37       Care must be taken not to grab for too long since other client programs
38       are locked out.  Also if a grabbing program hangs then the server will
39       be unusable until the program is killed, or its TCP etc server
40       connection is broken.
41
42   Weak $X
43       If Perl weak references are available (which means Perl 5.6 and up and
44       "Scalar::Util" with its usual XS code), then a grab object holds only a
45       weak reference to the target $X connection.  This means the grab
46       doesn't keep the connection alive once nothing else is interested.
47       When a connection is destroyed the server ungrabs automatically and so
48       there's no need for an explicit "UngrabServer()" in that case.
49
50       The main effect of the weakening is that $X can be garbage collected
51       anywhere within a grabbing block, the same as if there was no grab.
52       Without the weakening it would wait until the end of the block.  In
53       practice this only rarely makes a difference.
54
55       In the future if an "X11::Protocol" connection gets a notion of an
56       explicit close then the intention would be to skip any "UngrabServer()"
57       in that case too, ie. treat a closed connection the same as a weakened
58       away connection.
59
60       Currently no attention is paid to whether the server has disconnected
61       the link.  A "UngrabServer()" is done on destroy in the usual way.  If
62       the server has disconnected then a "SIGPIPE" or "EPIPE" occurs the same
63       as for any other request sent to the $X.
64

FUNCTIONS

66       "$g = X11::Protocol::GrabServer->new ($X)"
67           $X is an "X11::Protocol" object.  Create and return a $g object
68           representing a grab of the $X server.
69
70           If this new $g is the first new grab on $X then an "$X->GrabServer"
71           is done.
72
73       "$g->ungrab ()"
74           Ungrab the $g object explicitly.  An ungrab is done automatically
75           when $g is destroyed, but "$g->ungrab()" can do it sooner.
76
77           If $g is already ungrabbed then do nothing.
78
79       "$g->grab ()"
80           Re-grab with the $g object.  This can be used after a
81           "$g->ungrab()" to grab again with the same object, the same as if
82           newly created.
83
84           If $g is already grabbing then do nothing.
85
86       "$bool = $g->is_grabbed ()"
87           Return true if $g is grabbing.  This is true when first created, or
88           false after a "$g->ungrab()".
89
90           This function is only the state of $g.  There might be other
91           "GrabServer" objects which grabbing the server.
92

HOME PAGE

97       <http://user42.tuxfamily.org/x11-protocol-other/index.html>
98

LICENSE

100       Copyright 2010, 2011, 2012, 2013, 2014, 2017 Kevin Ryde
101
102       X11-Protocol-Other is free software; you can redistribute it and/or
103       modify it under the terms of the GNU General Public License as
104       published by the Free Software Foundation; either version 3, or (at
105       your option) any later version.
106
107       X11-Protocol-Other is distributed in the hope that it will be useful,
108       but WITHOUT ANY WARRANTY; without even the implied warranty of
109       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
110       General Public License for more details.
111
112       You should have received a copy of the GNU General Public License along
113       with X11-Protocol-Other.  If not, see <http://www.gnu.org/licenses/>.
114
115
116
117perl v5.36.0                      2022-07-22      X11::Protocol::GrabServer(3)

NAME

SYNOPSIS

DESCRIPTION

FUNCTIONS

SEE ALSO

HOME PAGE

LICENSE