diff options
Diffstat (limited to 'lib/common_test/doc/src/ct_slave.xml')
| -rw-r--r-- | lib/common_test/doc/src/ct_slave.xml | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/lib/common_test/doc/src/ct_slave.xml b/lib/common_test/doc/src/ct_slave.xml new file mode 100644 index 0000000000..44a7b7873f --- /dev/null +++ b/lib/common_test/doc/src/ct_slave.xml @@ -0,0 +1,221 @@ +<?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) -> 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) -> 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) -> 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) -> 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) -> 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> + + |