PolytreeDE
/
polybar
mirror of https://github.com/polybar/polybar.git
1
0
Fork 0
Code Releases Activity
polybar/doc/user/ipc.rst

108 lines
3.0 KiB
ReStructuredText
Raw Normal View History

Use sockets for IPC (#2539) Deprecates not using `polybar-msg` for IPC. Fixes #2532 Closes #2465 Fixes #2504 * Create FIFO specific NamedPipeHandle subclass to PipeHandle * Prototype SocketHandle * Move mainloop up to main.cpp * Pass eventloop to ipc class * Deprecate sending ipc over the named pipe Unfortunately, we can only show the warning in the polybar log and not give the user any feedback because the pipe is one-way * Move eventloop into its own namespace * Prototype ipc socket handling * Remove handles from ipc_client Should be independent from eventloop logic * Remove ipc clients when finished * Add tests for ipc_client decoding * Add callback for complete ipc messages * Remove template param from mixins * Move signal handler to new callback system * Move poll handle to new callback system * Move FSEventHandle to new callback system * Move TimerHandle and AsyncHandle to new callback system * Move PipeHandle to new callback system * Implement socket functionality in new callback system * Correctly reset ipc named pipe handle * Let client close handles in error callback * Wrap client pipe and ipc::client in connection class * Better decoder log messages * Socket path logic * Fix CI warnings * Remove UVHandleGeneric * Fix error when socket folder already exists * Proof of concept message writeback * Restructure ipc files * polybar-msg: Use sockets * polybar-msg: Better syntax for actions * Fix memory leak with fifo After EOF, the pipe wasn't closed and EOF was called all the time, each time allocating a new pipe. * Make polybar-msg compile on its own * Rudimentary writeback for polybar-msg * Fix payload reference going out of scope. * Add IPC documentation * Cleanup polybar-msg code * Specify the v0 ipc message format * Close ipc connection after message * Fix ipc tests * Properly close ipc connections * Fix polybar-msg not working with action string * Write polybar-msg manpage * polybar-msg: Stop using exit() * ipc: Print log message with PID * Add tests for ipc util * polybar-msg: Print PID with success message * ipc: Propagate message errors * Rename ipc::client to ipc::decoder * Rename ipc.cpp to polybar-msg.cpp * ipc: Write encoder function and fix decoder bugs * ipc: Use message format for responses * ipc: Handle wrong message types * ipc: Write back error message if ipc message cannot be processed This only happens for commands and empty actions. Non-empty actions are not immediately executed, but deferred until the next loop iteration. * Remove TODO about deleting runtime directory The socket file is not deleted after socket.close() is called, only after libuv executes the close callback. So we can't just call rmdir because it will probably always fail. * CLeanup WriteRequest * Update manpage authors * Cleanup
2022-01-22 19:35:37 +00:00
Inter-process-messaging
=======================
Polybar supports controlling parts of the bar and its modules from the outside
through inter-process-messaging (IPC).
IPC is disabled by default and can be enabled by setting ``enable-ipc = true``
in the bar section.
By default polybar ships with the ``polybar-msg`` tool that is needed to send
messages to polybar.
.. note:: Starting with version 3.6.0, the underlying IPC mechanism has been
completely changed.
Writing directly to the named pipe to send IPC messages has been
deprecated, ``polybar-msg`` should be used exclusively
Everything you could do by directly writing to the named pipe, you
can also do using ``polybar-msg``.
In addition, hook messages are also deprecated; they are replaced by
actions on the :ref:`ipc module <actions-ipc>`.
Unless noted otherwise, everything in this guide is still valid for
older versions.
Sending Messages
----------------
``polybar-msg`` can be called on the commandline like this:
.. code-block:: shell
polybar-msg [-p <pid>] <type> <payload>
If the ``-p`` argument is specified, the message is only sent to the running
polybar instance with the given process ID.
Otherwise, the message is sent to all running polybar processes that have IPC
enabled.
.. note:: IPC messages are only sent to polybar instances running under the
same user as ``polybar-msg`` is running as.
The ``<type>`` argument is either :ref:`action <ipc-actions>` or
:ref:`cmd <ipc-commands>`.
The allowed values for ``<payload>`` depend on the type.
Message Types
-------------
.. _ipc-commands:
Commands
^^^^^^^^
Using ``cmd`` for ``<type>``, you can control certain aspects of the bar.
Available values for ``<payload>`` are:
* ``quit``: Terminates the bar
* ``restart``: Restarts the bar in-place
* ``hide``: Hides the bar
* ``show``: Makes the bar visible again, if it was hidden
* ``toggle``: Toggles between the hidden and visible state.
.. _ipc-actions:
Module Actions
^^^^^^^^^^^^^^
For the ``<type>`` ``action``, ``polybar-msg`` can execute
:doc:`module actions <actions>` in the bar.
An action consists of the name of the target module, the name of the action and an optional data string:
::
#<modulename>.<actionname>[.<data>]
More information about action strings and available actions can be found in
:doc:`actions`
For example, if you have a date module named ``date``, you can toggle between
the regular and alternative label with:
.. code-block:: shell
polybar-msg action "#date.toggle"
As an example for an action with data, say you have a menu module named
``powermenu``, you can open the menu level 0 using:
.. code-block:: shell
polybar-msg action "#powermenu.open.0"
.. note::
For convenience, ``polybar-msg`` also allows you to pass the module name,
action name, and data as separate arguments:
.. code-block:: shell
polybar-msg action date toggle
polybar-msg action powermenu open 0
.. versionadded:: 3.6.0