Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
X11::Protocol::GrabSerUser3Contributed Perl DocumeX11::Protocol::GrabServer(3)

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

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

       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	outermost 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
       object like the synopsis	above is typical.  It's	also possible to hold
       a grab object for an extended time, perhaps for some state driven
       interaction with	the server.

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

   Weak	$X
       If Perl weak references are available (which means Perl 5.6 and up and
       "Scalar::Util" with its usual XS	code), then a grab object holds	only a
       weak reference to the target $X connection.  This means the grab
       doesn't keep the	connection alive once nothing else is interested.
       When a connection is destroyed the server ungrabs automatically and 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.

       "$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	explicitly.  An	ungrab is done automatically
	   when	$g is destroyed, but "$g->ungrab()" can	do it sooner.

	   If $g is already ungrabbed then do nothing.

       "$g->grab ()"
	   Re-grab with	the $g object.	This can be used after a
	   "$g->ungrab()" to grab again	with 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()".

	   This	function is only the state of $g.  There might be other
	   "GrabServer"	objects	which grabbing the server.

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


       Copyright 2010, 2011, 2012, 2013, 2014, 2017 Kevin Ryde

       X11-Protocol-Other is free software; you	can redistribute it and/or
       modify it under the terms of the	GNU 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 ANY WARRANTY; without even the implied warranty of
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with X11-Protocol-Other.	 If not, see <>.

perl v5.32.0			  2017-04-07	  X11::Protocol::GrabServer(3)


Want to link to this manual page? Use this URL:

home | help