X11::P...bServer(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 💖

okay so bestie, this is the object-oriented way to do GrabServer / UngrabServer on an X11::Protocol connection. A grab object is literally just a vibe that says "i want the server grabbed rn", and when it gets destroyed, it ungrabs. the way that works is so clean.

The first grab object on a connection does a GrabServer(), and the last one destroyed does an UngrabServer(). The whole idea? It's way easier to manage the lifespan of a grabbing object inside a block (or whatever) than to be out here making sure you've caught every single exit path. no cap. 🙈

Multiple grab objects can overlap or nest, and that's totally fine — only a single GrabServer() actually happens, and it stays grabbed until the very last object is destroyed. This is iconic for a library or a sub-function, where an UngrabServer() should wait until the end of the outermost desired grab. periodt.

A server grab is usually there to make a few operations atomic — think something global like root window properties. A block-based temporary object like the one in the synopsis is the typical move. You can also hold a grab object for an extended time, maybe for some state driven interaction with the server. 👑

⚠️ Care must be taken not to grab for too long, because 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. fr fr, don't leave the server on read. 💀

---

🎀 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. What that means: the grab doesn't keep the connection alive once nothing else is interested in it. And when a connection is destroyed, the server ungrabs automatically, so there's literally no need for an explicit UngrabServer() in that case. slay.

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 at all. Without the weakening, it would wait until the end of the block instead. In practice this only rarely makes a difference, ngl.

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. And 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 explicitly. An ungrab happens 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 it were 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(). Note that this function is only the state of $g — there might be other GrabServer objects which are grabbing the server. iykyk. 💅

---

🌸 SEE ALSO 🌸

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

---

🌈 HOME PAGE 🌈

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

---

💜 LICENSE 💜

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 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 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 <http://www.gnu.org/licenses/>.

---

and that's the whole page bestie 🎀 this little doc came from the User Contributed Perl Documentation collection, riding along with perl v5.28.1 and dated 2019-08-26. go grab that server (responsibly, pls, don't hang) 💖✨🦋