Re: Extend faq.using to discuss fork failures

[Christopher Faylor <cgf-use-the-mailinglist-please at cygwin dot com>]

On Tue, Aug 30, 2011 at 11:00:20AM +0200, Corinna Vinschen wrote:
>Hi Ryan,
>
>Thanks for the FAQ entry.  I had a look now, finally.  Two nits:
>
>On Aug 25 22:08, Ryan Johnson wrote:
>> Index: winsup/doc/faq-using.xml
>> ===================================================================
>> RCS file: /cvs/src/src/winsup/doc/faq-using.xml,v
>> retrieving revision 1.35
>> diff -u -r1.35 faq-using.xml
>> --- winsup/doc/faq-using.xml	4 Aug 2011 18:25:41 -0000	1.35
>> +++ winsup/doc/faq-using.xml	26 Aug 2011 01:58:44 -0000
>> @@ -1199,3 +1199,92 @@
>>  </listitem>
>>  </itemizedlist></para>
>>  </answer></qandaentry>
>> +<qandaentry id='faq.using.fixing-fork-failures'>
>> +  <question><para>Calls to <literal>fork</literal> fail a lot. How can
>> +  I fix the problem?</para></question>

I'd prefer a simple "How do I fix fork failures?"

>> +  <answer>
>> +
>> +  <para>Unix-like applications make extensive use of
>> +  <literal>fork</literal>, a function which spawns an exact copy of
>> +  the running process. Notable fork-using applications include bash
>> +  (and bash scripts), emacs, gcc, make, perl, python, and
>> +  ruby. Unfortunately, the Windows ecosystem is quite hostile to a
>> +  reliable fork implementation, leading to error messages such as:</para>

I'd prefer just going straight to the solution without worrying about
the theory or the ecosystem.  If more discussion is needed, as Corinna
says, point elsewhere.

So, a listing of potential errors followed by a succint explanation of
how to fix them is what I'd like to see.  You can move the "Windows ecosystem"
comments to the next section.

>> +  <para><itemizedlist>
>> +    <listitem>unable to remap <emphasis>$dll</emphasis> to same address as parent</listitem>
>> +    <listitem>couldn't allocate heap </listitem>
>> +    <listitem>died waiting for dll loading </listitem>
>> +    <listitem>child -1 - died waiting for longjmp before initialization</listitem>
>> +    <listitem>STATUS_ACCESS_VIOLATION </listitem>
>> +    <listitem>resource temporarily unavailable </listitem>
>> +  </itemizedlist></para>
>> +  <para>If you find that frequent fork failures interfere with normal
>> +  use of cygwin, please try the following: </para>

Please just use something like "Potential solutions for the above errors:"

>> +  <para><itemizedlist>
>> +    <listitem>Restart whatever process is trying (and failing) to use
>> +    <literal>fork</literal>. Sometimes Windows sets up a process
>> +    environment that is even more hostile to fork than usual.</listitem>
>> +    <listitem>Ensure that you have eliminated (not just disabled) all
>> +    software on the BLODA (see <ulink
>> +    url="http://cygwin.com/faq/faq.using.html#faq.using.bloda";
>> +    />)</listitem>
>> +    <listitem>Install the 'rebase' package, read its README in
>> +    <literal>/usr/share/doc/Cygwin</literal>, and follow the
>> +    instructions there to run 'rebaseall'.</listitem>
>
>The rebase package is always installed since it's part of the Base
>category.  This entry should be rephrased accordingly.
>
>> +    </itemizedlist></para>
>> +  <para>Please note that installing new packages or updating existing
>> +  ones often undoes the effects of rebaseall and cause fork failures
>> +  to reappear. If so, just run rebaseall again.
>> +  </para></answer>
>> +</qandaentry>
>> +<qandaentry id='faq.using.why-fork-fails'>
>> +  <question><para>Why does <literal>fork</literal> fail so much,
>> +  anyway? (or: Why does <literal>fork</literal> still fail even though
>> +  I ran rebaseall?)</para></question>
>> +  <answer>
>> +  <para>The semantics of <literal>fork</literal> require that a forked
>> +  child process have <emphasis>exactly</emphasis> the same address
>> +  space layout as its parent. However, Windows provides no native
>> +  support for cloning address space between processes and several
>> +  features actively undermine a reliable <literal>fork</literal>
>> +  implementation.
>
>Everything else which follows from here is a good description of the
>inner workings, but that shouldn't go into the FAQ.  What about creating
>a link to the user's guide "Process Creation" section here.  The technical
>details could then go into the "Process Creation" section.

I agree.  I should have thought of that when I mentioned making two
sections.

cgf