Tanu Kaskinen <tanu.kaskinen at linux.intel.com> [2014-08-25 13:53:38 +0300]:
>
> We should document what the purpose of the --check operation is. The
> implementation details don't matter, unless there are some caveats that
> the user should be aware of.
>
Agree, except in cases (such as --check, unfortunately) where it seems
impossible to accurately describe what "the operation" is without referring
to details which are _at present_ implementation dependent.
The only reason I brought XDG_RUNTIME_DIR and HOME into the description is
because (as you say below) there just doesn't seem to be a succinct way to
describe what "the operation" is, without referring to those environment
variables.
Hopefully, after I get the Wiki writeup in place so that it can be cited as
an authoritative referece, this problem will go away, and it will become
possible for the man page blurb to be succinct, and let the Wiki writeup
do the heavy lifting.
>
> I have so far thought that the purpose of --check is to check if there's
> a daemon running for the calling user, but actually, I don't think
> that's correct. Checking whether there's a daemon running for the
> calling user makes sense only if there can be only one daemon running
> for one user, and that's not the case (one example would be a scenario
> where the user has one regular daemon running, and then the user runs a
> PulseAudio test suite that starts another daemon for the tests under the
> same user but in a different environment).
Yes, stuff like this is exactly why I was trying to dispense with some sort
of "succinct description" of the option and just fall back to describing
how the option behaves functionally in the present implementation, and let
the reader infer whether that behavior gives him what he wants.
I think there are other examples too, that significantly complicate the
notion of "a daemon running for the calling user". Ssee attached questions
below.
> describe the real purpose. It's something like "check if there's a
> daemon running in the current environment". I think in the current
> implementation "the current environment" means of the effective UID and
> the XDG_RUNTIME_DIR and HOME environment variables. I'm not sure if the
> definition of "the current environment" is an implementation detail, or
> something that can be assumed not to change. It seems more like an
> implementation detail.
>
I understand what you're getting at. In the Wiki writeup, I'll take a stab
at disambiguating between a "stable API" description vs. the "current
implementation" description. It's going to be tricky.
> If you wonder why I included the effective UID in the environment, even
> if the code doesn't currently take it into consideration, the reason is
> that the result depends on the effective UID too. Running --check under
> different users in with the same environment variables results in
> different answers, if only one of the users has access to the runtime
> directory.
>
Yep, understand and agree.
My assumption in the draft writeup was that by giving a purely functional
description of --check in terms of XDG_RUNTIME_DIR and HOME, that the reader
would be able to infer the implications of the target directories being
potentially unreadable/unwritable by the invoking user.
Anyway, the detailed Wiki writeup will avoid the need for mentioning a lot of
this stuff in the man page itself, and instead just refer to the Wiki for
those details.
Here are some pre-questions that I'll need to understand before even starting
to tackle the Wiki description of the runtime dirs and pid files:
============================================================================
* --start:
"Start PulseAudio if it is not running yet. This is different from
starting PulseAudio without --start which would fail if PA is already
running."
Q1: What is the semantic distinction between those two sentences?
Parsing straightforwardly seems to lead to this:
If (--start option is specified on cmdline)
{
if (PA is not running)
{
Start PA;
}
else # PA is running
{
Don't start PA; # What exit code is supplied?
}
}
else # PA is not specfied on cmdline
{
if (PA running)
{
Don't start PA, and return nonzero exit code;
}
else # PA is not running
{
Start PA;
}
}
But the outer if/else seem to have no distinction between them, other
than (perhaps) the exit code supplied by the top clause may differ from
the explicitly nonzero error code of the bottom clause. Is there any other
difference?
Q2: In the above pseudocode, how are the tests for running-ness performed?
Q3: Related to Q2 and Q7 below: What if there are multiple PAs running,
some of which may have been started with --use-pid-file=0?. Are these
non-PIDfile-d PA's included in the notion of "running" as used in
the above --start option description?
============================================================================
* --kill:
"Kill an already running PulseAudio daemon of the calling user.
(Equivalent to sending a SIGTERM)."
Q4: (Ok, this not really a question but an obsevation): The same ambiguity
issue exists here as for --check, i.e regarding which PA daemon is being
referred to, and what "calling user" might mean. Whatever way I wind up
solving the doc issue for --check will have to be applied here as well.
============================================================================
* --daemonize[=BOOL]
"Daemonize after startup, i.e. detach from the terminal."
Q5: Is there any interaction between this option and the creation (or not)
of a PID file? I.e., if --daemonize=0, does it still create a pid file?
Please tell me the answer to the latter question is "yes", otherwise
I'm going to have to start drinking heavily because it will roughly
quadruple the complexity of what I need to describe in the Wiki writeup.
(So you should feel free to lie to me about it and say "yes", lol...)
============================================================================
* --use-pid-file=[BOOL]
"Create a PID file. If this options is disabled it is possible to run
multiple sound servers per user."
Q6: Suppose one or more PA daemons have been started with --use-pid-file=0
(hence there are no pid files corresponding to these daemon processes.)
In this case, is it possible to use --kill or --check to refer to such
daemon process(es)? [Quick experiments seem to indicate answer is "no"]
Q7: Same as Q7, but w.r.t. "--start" option: How is the "--start" pseudocode
in Q1 affected by the possible presence of running PA daemon(s) that have
no associated PID file(s)?
============================================================================
