From 8721a339485b52af5c609c1f89b8399d8d6163d8 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 29 Nov 2015 10:42:57 +0100 Subject: add almost all examples to info MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- doc/info/bus.texinfo | 743 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 740 insertions(+), 3 deletions(-) (limited to 'doc/info/bus.texinfo') diff --git a/doc/info/bus.texinfo b/doc/info/bus.texinfo index 2a24cc1..d71a4fd 100644 --- a/doc/info/bus.texinfo +++ b/doc/info/bus.texinfo @@ -74,6 +74,7 @@ Texts. A copy of the license is included in the section entitled * Interface:: Using @command{libbus}. * Protocol:: How communication over @command{bus} works internally. * Rationale:: Why @command{bus}? +* Examples:: Usecase examples and API-demonstration. * GNU Free Documentation License:: Copying and sharing this manual. @end menu @c TODO @detailmenu (`C-c C-u m`) @@ -679,13 +680,749 @@ exits, or if the call fails.@* @node Rationale @chapter Rationale -We need an interprocess communication system similar to message queues. -But we need broadcasting rather than anycasting, so we have a fast, -simple and daemonless system for announcing events to any processes that +We need an interprocess communication system similar +to message queues. But we need broadcasting rather than +anycasting, so we have a fast, simple and daemonless +system for announcing events to any processes that might be interested. +@node Examples +@chapter Examples + +This chapter contains usecase examples and +API-demonstrations. You will find that they are (on +a standard installation) installed on your system. + +@menu +* Audio-volume control:: +* Telephony and music:: +* Timed:: +* Nonblocking:: +* Daemon-depedencies:: +@end menu + + + + +@node Audio-volume control +@section Audio-volume control + +Assume you have program that display the audio volume. +This program checks every second third if the volume +have changed. + +Also assume that you use @command{amixer} to change the +volume, most often by using keybindings via @command{xbindkeys}. + +To reduce the delay, you want to send a signal to the +monitor program that the volume have changed. For this +more primitive IPC is sufficient, but lets assume there +are other programs interested in this information too. + +To accomplish this, you create a wrapper for @command{amixer} +that broadcasts updates on a bus. This wrapper is +installed as @command{~/.local/bin/amixer}, and +@command{~/.local/bin/} is included in @env{$PATH} +before @command{/usr/bin}. +@* + +@noindent +Before starting run @command{./init}, this code is +should be run from your profile file if you want to +implement this on your system. After running +@command{./init}, you can start one or more listeners +by running @command{./alsa-monitor}. + +To change the volume run +@code{./amixer -c 0 -- set Master 5%+} or similar. + +When you are done run @command{./cleanup}. + + +@subsubheading @file{./amixer} +@example +#!/bin/sh +/usr/bin/amixer "$@@" +for arg in "$@@"; do + if [ "$@{arg@}" = "set" ] || \ + [ "$@{arg@}" = "sset" ] || \ + [ "$@{arg@}" = "cset" ]; then + exec bus broadcast "/tmp/example-bus" '0 volume-changed *' + fi +done +@end example + + +@subsubheading @file{./cleanup} +@example +#!/bin/sh +exec bus remove "/tmp/example-bus" +@end example + + +@subsubheading @file{./init} +@example +#!/bin/sh +bus create "/tmp/example-bus" + +# @w{@xrm{}The following code is more suitable in the real world,@xtt{}} +# @w{@xrm{}if used, the other files should use @xtt{}"$@{BUS_AUDIO@}"} +# @w{@xrm{}instead of @xtt{}"/tmp/example-bus"@xrm{}.@xtt{}} +# +# export BUS_AUDIO="$@{XDG_RUNTIME_DIR@}/bus/audio" +# if [ ! -f "$@{BUS_AUDIO@}" ]; then +# bus create "$@{BUS_AUDIO@}" +# fi +@end example + + +@subsubheading @file{./monitor} +@example +#!/bin/sh +if [ $# = 1 ]; then + if [ "$(echo "$@{1@}" | cut -d ' ' -f 2)" = "volume-changed" ]; then + printf '\e[H\e[2J' + amixer get Master + fi + exit 0 +fi + +exec 2>/dev/null + +printf '\e[?1049h\e[H\e[2J' +trap -- "printf '\e[?1049l'" SIGINT +bus listen "/tmp/example-bus" \'"$@{0/\'/\'\\\'\'@}"\'' "$@{msg@}"' +@end example + + + +@node Telephony and music +@section Telephony and music + +Assume you have a music player and a telephony program. +You might like it if the music player pauses whenever +you make or receive a call. You may also like it, if +the music resumed when the call ended. + +In this example we will assume you the have @command{mocp} +(@command{moc} package) running. And we will use the shell to +simulate a telephony program. +@* + +@noindent +First of, run make to build this example. Before +starting run @command{./init}. And when you are +done run @command{./cleanup}. + +In one terminal run @command{./monitor}. This program +will pause @command{mocp} when you make or receive a call, +it will also resume @command{mocp} when all calls have +ended if it did pause @command{mocp}. + +Then start any positive number of terminals. +We will pretend that each of them are telephony +programs. To make or receive a call, run +@command{./receive-or-make-call}, when you want to +end the pretend call, run @command{./end-call} from +the terminal (or more accurately, from the same +process.) + + +@subsubheading @file{./Makefile} +@example +COMMANDS = init cleanup monitor end-call receive-or-make-call + +all: $@{COMMANDS@} +%: %.c + $@{CC@} -Wall -Wextra -pedantic -std=c99 -lbus -o $@@ $< +clean: + -rm $@{COMMANDS@} + +.PHONY: all clean +@end example + + +@subsubheading @file{./cleanup.c} +@example +#include +#include + +int main() +@{ + return bus_unlink("/tmp/example-bus") && (perror("cleanup"), 1); +@} +@end example + + +@subsubheading @file{./end-call.c} +@example +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +static char message[BUS_MEMORY_SIZE]; + +int main() +@{ + bus_t bus; + sprintf(message, "%ji unforce-pause", (intmax_t)getppid()); + /* @w{@xrm{}Yes, PPID; in this example we pretend the shell is the telephony process.@xtt{}} */ + t (bus_open(&bus, "/tmp/example-bus", BUS_WRONLY)); + t (bus_write(&bus, message, 0)); + bus_close(&bus); + return 0; + +fail: + perror("end-call"); + bus_close(&bus); + return 1; +@} +@end example + + +@subsubheading @file{./init.c} +@example +#include +#include + +int main() +@{ + return bus_create("/tmp/example-bus", 0, NULL) && (perror("init"), 1); +@} +@end example + + +@subsubheading @file{./monitor.c} +@example +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +static size_t pauser_count = 0; +static size_t pausers_size = 0; +static char* pausers = NULL; + +static int is_moc_playing(void) +@{ + return !WEXITSTATUS(system("env LANG=C mocp -i 2>/dev/null |" + "grep 'State: PLAY' >/dev/null")); +@} + +/* @w{@xrm{}In a proper implementation, message whould be copyied, and then@xtt{}} + * @w{@xrm{}a new thread would be created that parsed the copy. But that is@xtt{}} + * @w{@xrm{}too much for an example, especially since it would also require@xtt{}} + * @w{@xrm{}a mutex to make sure two threads do not modify data at the same@xtt{}} + * @w{@xrm{}time, causing chaos.@xtt{}} */ +static int callback(const char *message, void *user_data) +@{ + char *msg = NULL; + size_t len = 0; + if (message == 0) + return 1; + while ((len < 2047) && message[len]) + len++; + msg = malloc((len + 1) * sizeof(char)); + t (msg == NULL); + memcpy(msg, message, len * sizeof(char)); + msg[len] = 0; + /* @w{@xrm{}BEGIN run as in a separate thread@xtt{}} */ + if (pauser_count || is_moc_playing()) @{ + char *begin = strchr(msg, ' '); + ssize_t pid; + int requests_pause; + if (begin == NULL) + goto done; + *begin++ = 0; + pid = (ssize_t)atoll(msg); + if (pid < 1) /* @w{@xrm{}We need a real PID, too bad there is@xtt{}} + * @w{@xrm{}no convient way to detect if it dies.@xtt{}} */ + goto done; + if ((strstr(begin, "force-pause ") == begin) || + !strcmp(begin, "force-pause")) + requests_pause = 1; + else if ((strstr(begin, "unforce-pause ") == begin) || + !strcmp(begin, "unforce-pause")) + requests_pause = 0; + else + goto done; + if ((size_t)pid >= pausers_size) @{ + pausers = realloc(pausers, (size_t)(pid + 1) * sizeof(char)); + t (pausers == NULL); /* @w{@xrm{}Let's ignore the memory leak.@xtt{}} */ + memset(pausers + pausers_size, 0, + ((size_t)(pid + 1) - pausers_size) * sizeof(char)); + pausers_size = (size_t)(pid + 1); + @} + if (pausers[pid] ^ requests_pause) @{ + pauser_count += requests_pause ? 1 : -1; + pausers[pid] = requests_pause; + if (pauser_count == (size_t)requests_pause) + system(requests_pause ? "mocp -P" : "mocp -U"); + @} + @} + /* @w{@xrm{}END run as in a separate thread@xtt{}} */ + goto done; + (void) user_data; + +fail: + perror("monitor"); + return -1; + +done: + free(msg); + return 1; +@} + +int main() +@{ + bus_t bus; + t (bus_open(&bus, "/tmp/example-bus", BUS_RDONLY)); + t (bus_read(&bus, callback, NULL)); + bus_close(&bus); + free(pausers); + return 0; + +fail: + perror("monitor"); + bus_close(&bus); + free(pausers); + return 1; +@} +@end example + + +@subsubheading @file{./receive-or-make-call.c} +@example +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +static char message[BUS_MEMORY_SIZE]; + +int main() +@{ + bus_t bus; + sprintf(message, "%ji force-pause", (intmax_t)getppid()); + /* @w{@xrm{}Yes, PPID; in this example we pretend the shell is the telephony process.@xtt{}} */ + t (bus_open(&bus, "/tmp/example-bus", BUS_WRONLY)); + t (bus_write(&bus, message, 0)); + bus_close(&bus); + return 0; + +fail: + perror("receive-or-make-call"); + bus_close(&bus); + return 1; +@} +@end example + + + +@node Timed +@section Timed + +This example shows how to use timed operations. + +First of, run make to build this example. + +To start the example run @command{./init}. When you are +done run @command{./cleanup}. + +Running instances of @command{./poll} will wait for new +messages continuously, but with one second timeouts. + +@command{./slow-poll} works like @command{./poll}, except +it will sleep for one second every time it receives +a message. + +Running instances of @command{./read} will read for ten +seconds and then time out. + +@command{./poll}, @command{./read}, and @command{./slow-poll} +will stop if the message "stop" is broadcasted. + +@command{./write} will wait for atmost a tenth of a +seconds before failing. This means that if two instances +of @command{./write} is started at the same time one of +them will fail if @command{./slow-poll} is running. + +@command{./poll}, @command{./read}, @command{./init} and +@command{./cleanup} are run without any additional +arguments. @command{./write} is run with the message +as the second argument. + + +@subsubheading @file{./Makefile} +@example +COMMANDS = init cleanup write poll read slow-poll + +all: $@{COMMANDS@} +%: %.c + $@{CC@} -Wall -Wextra -pedantic -std=c99 -lbus -o $@@ $< +clean: + -rm $@{COMMANDS@} + +.PHONY: all clean +@end example + + +@subsubheading @file{./cleanup.c} +@example +#include +#include + +int main() +@{ + return bus_unlink("/tmp/example-bus") && (perror("cleanup"), 1); +@} +@end example + + +@subsubheading @file{./init.c} +@example +#include +#include + +int main() +@{ + return bus_create("/tmp/example-bus", 0, NULL) && (perror("init"), 1); +@} +@end example + + +@subsubheading @file{./poll.c} +@example +#include +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +int main() +@{ + bus_t bus; + const char *message; + long long tick = 0; + struct timespec timeout; + t (bus_open(&bus, "/tmp/example-bus", BUS_RDONLY)); + t (bus_poll_start(&bus)); + for (;;) @{ + t(clock_gettime(CLOCK_MONOTONIC, &timeout)); + timeout.tv_sec += 1; + message = bus_poll_timed(&bus, &timeout, CLOCK_MONOTONIC); + if (message == NULL) @{ + t (errno != EAGAIN); + printf("waiting... %lli\n", ++tick); + continue; + @} + tick = 0; + message = strchr(message, ' ') + 1; + if (!strcmp(message, "stop")) + break; + printf("\033[01m%s\033[21m\n", message); + @} + t (bus_poll_stop(&bus)); + bus_close(&bus); + return 0; + +fail: + perror("poll"); + bus_poll_stop(&bus); + bus_close(&bus); + return 1; +@} +@end example + + +@subsubheading @file{./read.c} +@example +#include +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +static int callback(const char *message, void *user_data) +@{ + (void) user_data; + + if (message == NULL) + return 1; + + message = strchr(message, ' ') + 1; + if (!strcmp(message, "stop")) + return 0; + printf("%s\n", message); + return 1; +@} + +int main() +@{ + bus_t bus; + struct timespec timeout; + t (bus_open(&bus, "/tmp/example-bus", BUS_RDONLY)); + t (clock_gettime(CLOCK_MONOTONIC, &timeout)); + timeout.tv_sec += 10; + t (bus_read_timed(&bus, callback, NULL, &timeout, CLOCK_MONOTONIC)); + bus_close(&bus); + return 0; + +fail: + perror("poll"); + bus_poll_stop(&bus); + bus_close(&bus); + return 1; +@} +@end example + + +@subsubheading @file{./slow-poll.c} +@example +#include +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +int main() +@{ + bus_t bus; + const char *message; + long long tick = 0; + struct timespec timeout; + t (bus_open(&bus, "/tmp/example-bus", BUS_RDONLY)); + t (bus_poll_start(&bus)); + for (;;) @{ + t (clock_gettime(CLOCK_MONOTONIC, &timeout)); + timeout.tv_sec += 1; + message = bus_poll_timed(&bus, &timeout, CLOCK_MONOTONIC); + if (message == NULL) @{ + t (errno != EAGAIN); + printf("waiting... %lli\n", ++tick); + continue; + @} + tick = 0; + message = strchr(message, ' ') + 1; + if (!strcmp(message, "stop")) + break; + printf("\033[01m%s\033[21m\n", message); + sleep(1); + @} + t (bus_poll_stop(&bus)); + bus_close(&bus); + return 0; + +fail: + perror("poll"); + bus_poll_stop(&bus); + bus_close(&bus); + return 1; +@} +@end example + + +@subsubheading @file{./write.c} +@example +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +static char message[BUS_MEMORY_SIZE]; + +int main(int argc, char *argv[]) +@{ + bus_t bus; + struct timespec timeout; + if (argc < 2) @{ + fprintf(stderr, "%s: USAGE: %s message\n", argv[0], argv[0]); + return 2; + @} + sprintf(message, "0 %s", argv[1]); + t (bus_open(&bus, "/tmp/example-bus", BUS_WRONLY)); + t (clock_gettime(CLOCK_MONOTONIC, &timeout)); + timeout.tv_nsec += 100000000L; + t (bus_write_timed(&bus, message, &timeout, CLOCK_MONOTONIC)); + bus_close(&bus); + return 0; + +fail: + perror("write"); + bus_close(&bus); + return 1; +@} +@end example + + + +@node Nonblocking +@section Nonblocking + +This example shows how to use bus_poll instead of bus_read, +and how to do non-blocking polling and non-blocking writing. + +First of, run make to build this example. + +To start the example run @command{./init}. When you are done +run @command{./cleanup}. + +Running instances of @command{./poll} will check every second +if there is a new inbound message. Between these checks +@command{./write} will wait for all @command{./poll}:s to +receive the message. This means that @command{./write} blocks +while @command{./poll} sleeps. If two or more instances of +@command{./write} is started at approximately the same time, +only one will continue to write a message on the bus, the +others will fail. + +@command{./poll} will stop if the message ``stop'' is +broadcasted. + +@command{./poll}, @command{./init} and @command{./cleanup} +are run without any additional arguments. @command{./write} +is run with the message as the second argument. + + +@subsubheading @file{./Makefile} +@example +COMMANDS = init cleanup write poll + +all: $@{COMMANDS@} +%: %.c + $@{CC@} -Wall -Wextra -pedantic -std=c99 -lbus -o $@@ $< +clean: + -rm $@{COMMANDS@} + +.PHONY: all clean +@end example + + +@subsubheading @file{./cleanup.c} +@example +#include +#include + +int main() +@{ + return bus_unlink("/tmp/example-bus") && (perror("cleanup"), 1); +@} +@end example + + +@subsubheading @file{./init.c} +@example +#include +#include + +int main() +@{ + return bus_create("/tmp/example-bus", 0, NULL) && (perror("init"), 1); +@} +@end example + + +@subsubheading @file{./poll.c} +@example +#include +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +int main() +@{ + bus_t bus; + const char *message; + long long tick = 0; + t (bus_open(&bus, "/tmp/example-bus", BUS_RDONLY)); + t (bus_poll_start(&bus)); + for (;;) @{ + message = bus_poll(&bus, BUS_NOWAIT); + if (message == NULL) @{ + t (errno != EAGAIN); + printf("waiting... %lli\n", ++tick); + sleep(1); + continue; + @} + tick = 0; + message = strchr(message, ' ') + 1; + if (!strcmp(message, "stop")) + break; + printf("\033[01m%s\033[21m\n", message); + @} + t (bus_poll_stop(&bus)); + bus_close(&bus); + return 0; + +fail: + perror("poll"); + bus_poll_stop(&bus); + bus_close(&bus); + return 1; +@} +@end example + + +@subsubheading @file{./write.c} +@example +#include +#include +#include +#include + +#define t(stmt) if (stmt) goto fail + +static char message[BUS_MEMORY_SIZE]; + +int main(int argc, char *argv[]) +@{ + bus_t bus; + if (argc < 2) @{ + fprintf(stderr, "%s: USAGE: %s message\n", argv[0], argv[0]); + return 2; + @} + sprintf(message, "0 %s", argv[1]); + t (bus_open(&bus, "/tmp/example-bus", BUS_WRONLY)); + t (bus_write(&bus, message, BUS_NOWAIT)); + bus_close(&bus); + return 0; + +fail: + perror("write"); + bus_close(&bus); + return 1; +@} +@end example + + + +@node Daemon-depedencies +@section Daemon-depedencies + +TODO + + + @node GNU Free Documentation License @appendix GNU Free Documentation License @include fdl.texinfo -- cgit v1.2.3-70-g09d2