<!--
  ~ Copyright 2011 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<chapter id='gradle_daemon'>
    <title>The Gradle Daemon</title>

    <section id='enter_the_daemon'>
        <title>Enter the daemon</title>
        <para><emphasis>The Gradle daemon</emphasis> (sometimes referred as <emphasis>the build daemon</emphasis>)
            aims to improve the startup and execution time of Gradle.
        </para>

        <para>
            We came up with several use cases where the daemon is very useful.
            For some workflows, the user invokes Gradle many times to execute a small number of relatively quick tasks.
            For example:
            <itemizedlist>
                <listitem>When using test driven development, where the unit tests are executed many times.</listitem>
                <listitem>When developing a web application, where the application is assembled many times.</listitem>
                <listitem>When discovering what a build can do, where <userinput>gradle tasks</userinput> is executed a number of times.</listitem>
            </itemizedlist>
            For these workflows, it is important that the startup cost of invoking Gradle is as small as possible.
        </para>
        <para>
            In addition, user interfaces can provide some interesting features if the Gradle model can be built relatively quickly.
            For example, the daemon might be useful for the following scenarios:
            <itemizedlist>
                <listitem>Content assistance in the IDE</listitem>
                <listitem>Live visualisation of the build in a GUI</listitem>
                <listitem>Tab completion in a CLI</listitem>
            </itemizedlist>
        </para>
        <para>
            In general, snappy behavior of the build tool is always handy.
            If you try using the daemon for your local builds, you won't want to go back.
        </para>
        <para>
            The Tooling API (see <xref linkend="embedding"/>)
            uses the daemon all the time, e.g. you cannot officially use the Tooling API without the daemon.
            This means that whenever you are using the STS Gradle plugin for Eclipse or the Gradle support in Intellij IDEA,
            you're already using the Gradle Daemon.
        </para>
        <para>In the future, there are plans for more features in the daemon:
            <itemizedlist>
                <listitem>Snappy up-to-date checks: use native file system change notifications (e.g. via jdk7 nio.2)
                    to preemptively perform up-to-date analysis.</listitem>
                <listitem>Even faster builds: preemptively evaluate projects, so that the model is ready
                    when the user next invokes Gradle.</listitem>
                <listitem>Did we mention faster builds? The daemon can potentially preemptively download dependencies
                    or check for new versions of snapshot dependencies.</listitem>
                <listitem>Utilize a pool of reusable processes available for compilation and testing.
                    For example, both the Groovy and Scala compilers have a large startup cost.
                    The build daemon could maintain a process with Groovy and/or Scala already loaded.</listitem>
                <listitem>Preemptive execution of certain tasks, for example compilation. Quicker feedback.</listitem>
                <listitem>Fast and accurate bash tab completion.</listitem>
                <listitem>Periodically garbage collect the Gradle caches.</listitem>
            </itemizedlist>
        </para>
    </section>

    <section id='reusing_daemons'>
        <title>Reusing and expiration of daemons</title>
        <para>The basic idea is that the Gradle command forks a daemon process, which performs the actual build.
            Subsequent invocations of the Gradle command will reuse the daemon, avoiding the startup costs.
            Sometimes we cannot use an existing daemon because it is busy or its java version or jvm arguments are different.
            For exact details on when exactly a new daemon process is forked read the dedicated section below.
            The daemon process automatically expires after 3 hours of idle time.
        </para>
        <para>
            Here are all situations in which we fork a new daemon process:
            <itemizedlist>
                <listitem>If the daemon process is currently busy running some job, a brand new daemon process will be started.</listitem>
                <listitem>We fork a separate daemon process per java home. So even if there is some idle daemon waiting
                    for build requests but you happen to run a build with a different java home then a brand new daemon will be forked.</listitem>
                <listitem>We fork a separate daemon process if the jvm arguments for the build are sufficiently different.
                    For example we will not fork a new daemon if a some system property has changed.
                    However if the -Xmx memory setting changed or some fundamental immutable system property changed (e.g. file.encoding)
                    then a new daemon will be forked.
                </listitem>
                <listitem>At the moment the daemon is coupled with a particular version of Gradle.
                    This means that even if some daemon is idle but you are running the build
                    with a different version of Gradle, a new daemon will be started.
                    This also has a consequence for the <literal>--stop</literal> command line instruction:
                    this command will only stop daemons that were started with Gradle version that is executing <literal>--stop</literal>.
                </listitem>
            </itemizedlist>
            We plan to improve the functionality of managing and pooling the daemons in the future.
        </para>
    </section>

    <section id='daemon_usage_and_troubleshooting'>
        <title>Usage and troubleshooting</title>
        <para>For command line usage, look at the dedicated section in <xref linkend="gradle_command_line"/>.
            If you are tired of using the same command line options again and again, take a look at
            <xref linkend="sec:gradle_configuration_properties"/>.
            This section contains information on how to configure certain behavior of the daemon
            (including turning on the daemon by default) in a more 'persistent' way.
        </para>
        <para>
            Some ways of troubleshooting the Gradle daemon:
            <itemizedlist>
                <listitem>If you have a problem with your build, try temporarily disabling the daemon
                    (you can pass the command line switch <literal>--no-daemon</literal>).</listitem>
                <listitem>Occasionally, you may want to stop the daemons either via the <literal>--stop</literal>
                    command line option or in a more forceful way.</listitem>
                <listitem>There is a daemon log file, which by default is located in the
                    Gradle user home directory.</listitem>
                <listitem>You may want to start the daemon in <literal>--foreground</literal>
                    mode to observe how the build is executed.</listitem>
            </itemizedlist>
        </para>
    </section>

    <section id="sec:daemon_properties">
        <title>Configuring the daemon</title>
        <para>Some daemon settings, such as JVM arguments, memory settings or the Java home, can be configured.
            Please find more information in <xref linkend="sec:gradle_configuration_properties"/>
        </para>
    </section>

</chapter>
