<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2010</year><year>2012</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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.

    </legalnotice>

    <title>ct_slave</title>
    <prepared></prepared>
    <responsible></responsible>
    <docno></docno>
    <approved></approved>
    <checked></checked>
    <date></date>
    <rev>A</rev>
    <file>ct_slave.xml</file>
  </header>
  <module>ct_slave</module>
  <modulesummary>Common Test framework functions for starting and stopping
    nodes for Large-Scale Testing.</modulesummary>

  <description>

    <p><c>Common Test</c> framework functions for starting and stopping nodes
      for Large-Scale Testing.</p>

    <p>This module exports functions used by the <c>Common Test</c>
      Master to start and stop "slave" nodes. It is the default callback
      module for the <c>{init, node_start}</c> term in the Test
      Specification.</p>

  </description>

  <funcs>
    <func>
      <name>start(Node) -&gt; Result</name>
      <fsummary>Starts an Erlang node with name Node on the local
        host.</fsummary>
      <type>
        <v>Node = atom()</v>
        <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
        <v>Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive</v>
        <v>NodeName = atom()</v>
      </type>
      <desc><marker id="start-1"/>
        <p>Starts an Erlang node with name <c>Node</c> on the local host.</p>

        <p>See also
          <seealso marker="#start-3"><c>ct_slave:start/3</c></seealso>.</p>
      </desc>
    </func>

    <func>
      <name>start(HostOrNode, NodeOrOpts) -&gt; Result</name>
      <fsummary>Starts an Erlang node with default options on a specified
        host, or on the local host with specified options.</fsummary>
      <type>
        <v>HostOrNode = atom()</v>
        <v>NodeOrOpts = atom() | list()</v>
        <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
        <v>Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive</v>
        <v>NodeName = atom()</v>
      </type>
      <desc><marker id="start-2"/>
        <p>Starts an Erlang node with default options on a specified host, or
          on the local host with specified options. That is, the call is
          interpreted as <c>start(Host, Node)</c> when the second argument is
          atom-valued and <c>start(Node, Opts)</c> when it is list-valued.</p>

        <p>See also
          <seealso marker="#start-3"><c>ct_slave:start/3</c></seealso>.</p>
      </desc>
    </func>

    <func>
      <name>start(Host, Node, Opts) -&gt; Result</name>
      <fsummary>Starts an Erlang node with name Node on host Host as
        specified by the combination of options in Opts.</fsummary>
      <type>
        <v>Node = atom()</v>
        <v>Host = atom()</v>
        <v>Opts = [OptTuples]</v>
        <v>OptTuples = {username, Username} | {password, Password} | {boot_timeout, BootTimeout} | {init_timeout, InitTimeout} | {startup_timeout, StartupTimeout} | {startup_functions, StartupFunctions} | {monitor_master, Monitor} | {kill_if_fail, KillIfFail} | {erl_flags, ErlangFlags} | {env, [{EnvVar, Value}]}</v>
        <v>Username = string()</v>
        <v>Password = string()</v>
        <v>BootTimeout = integer()</v>
        <v>InitTimeout = integer()</v>
        <v>StartupTimeout = integer()</v>
        <v>StartupFunctions = [StartupFunctionSpec]</v>
        <v>StartupFunctionSpec = {Module, Function, Arguments}</v>
        <v>Module = atom()</v>
        <v>Function = atom()</v>
        <v>Arguments = [term]</v>
        <v>Monitor = bool()</v>
        <v>KillIfFail = bool()</v>
        <v>ErlangFlags = string()</v>
        <v>EnvVar = string()</v>
        <v>Value = string()</v>
        <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
        <v>Reason = already_started | started_not_connected | boot_timeout | init_timeout | startup_timeout | not_alive</v>
        <v>NodeName = atom()</v>
      </type>
      <desc><marker id="start-3"/>
        <p>Starts an Erlang node with name <c>Node</c> on host <c>Host</c> as
          specified by the combination of options in <c>Opts</c>.</p>

        <p>Options <c>Username</c> and <c>Password</c> are used to log on to the
          remote host <c>Host</c>. <c>Username</c>, if omitted, defaults to
          the current username. <c>Password</c> is empty by default.</p>

        <p>A list of functions specified in option <c>Startup</c> are
          executed after startup of the node. Notice that all used modules
          are to be present in the code path on <c>Host</c>.</p>

        <p>The time-outs are applied as follows:</p>

        <taglist>
          <tag><c>BootTimeout</c></tag>
            <item><p>The time to start the Erlang node, in seconds. Defaults to
              3 seconds. If the node is not pingable within this time, the result
              <c>{error, boot_timeout, NodeName}</c> is returned.</p></item>
          <tag><c>InitTimeout</c></tag>
            <item><p>The time to wait for the node until it calls the internal
             callback function informing master about a successful startup.
             Defaults to 1 second. In case of a timed out message, the result
             <c>{error, init_timeout, NodeName}</c> is returned.</p></item>
          <tag><c>StartupTimeout</c></tag>
            <item><p>The time to wait until the node stops to run
              <c>StartupFunctions</c>. Defaults to 1 second. If this time-out
              occurs, the result <c>{error, startup_timeout, NodeName}</c> is
              returned.</p></item>
        </taglist>

        <p><em>Options:</em></p>

        <taglist>
          <tag><c>monitor_master</c></tag>
          <item><p>Specifies if the slave node is to be stopped if the
            master node stops. Defaults to <c>false</c>.</p></item>
          <tag><c>kill_if_fail</c></tag>
          <item><p>Specifies if the slave node is to be killed if a time-out
            occurs during initialization or startup. Defaults to <c>true</c>.
            Notice that the node can also be still alive it the boot time-out
            occurred, but it is not killed in this case.</p></item>
          <tag><c>erlang_flags</c></tag>
          <item><p>Specifies which flags are added to the parameters of the
            executable <c>erl</c>.</p></item>
          <tag><c>env</c></tag>
          <item><p>Specifies a list of environment variables that will extend
            the environment.</p></item>
        </taglist>

        <p><em>Special return values:</em></p>

        <list type="bulleted">
          <item><p><c>{error, already_started, NodeName}</c> if the node
            with the specified name is already started on a specified
            host.</p></item>
          <item><p><c>{error, started_not_connected, NodeName}</c> if the
            node is started, but not connected to the master node.</p></item>
          <item><p><c>{error, not_alive, NodeName}</c> if the node on which
            <seealso marker="#start-3"><c>ct_slave:start/3</c></seealso> is
            called, is not alive. Notice that <c>NodeName</c> is the name of
            the current node in this case.</p></item>
        </list>
      </desc>
    </func>

    <func>
      <name>stop(Node) -&gt; Result</name>
      <fsummary>Stops the running Erlang node with name Node on the local
        host.</fsummary>
      <type>
        <v>Node = atom()</v>
        <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
        <v>Reason = not_started | not_connected | stop_timeout</v>
      </type>
      <desc><marker id="stop-1"/>
        <p>Stops the running Erlang node with name <c>Node</c> on the local
          host.</p>
      </desc>
    </func>

    <func>
      <name>stop(Host, Node) -&gt; Result</name>
      <fsummary>Stops the running Erlang node with name Node on host
        Host.</fsummary>
      <type>
        <v>Host = atom()</v>
        <v>Node = atom()</v>
        <v>Result = {ok, NodeName} | {error, Reason, NodeName}</v>
        <v>Reason = not_started | not_connected | stop_timeout</v>
        <v>NodeName = atom()</v>
      </type>
      <desc><marker id="stop-2"/>
        <p>Stops the running Erlang node with name <c>Node</c> on host
          <c>Host</c>.</p>
      </desc>
    </func>
  </funcs>

</erlref>


