aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc/src/ct_slave.xml
blob: ceebf51f1a1d5ecc96ebae4ee39d78c665da6a14 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<title>ct_slave</title>
<prepared></prepared>
<responsible></responsible>
<docno>1</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>Common Test Framework functions for starting and stopping nodes for   
Large Scale Testing.</p>
  
   <p>This module exports functions which are used by the Common Test Master
   to start and stop "slave" nodes. It is the default callback module for the
   <c>{init, node_start}</c> term of 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, already_started, NodeName} | {error, started_not_connected, NodeName} | {error, boot_timeout, NodeName} | {error, init_timeout, NodeName} | {error, startup_timeout, NodeName} | {error, not_alive, NodeName}</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><em>See also:</em> <seealso marker="#start-3">start/3</seealso>.</p>
</desc></func>
<func>
<name>start(Host, Node) -&gt; Result</name>
<fsummary>Starts an Erlang node with name Node on host
   Host with the default options.</fsummary>
<type>
<v>Node = atom()</v><v>Host = atom()</v><v>Result = {ok, NodeName} | {error, already_started, NodeName} | {error, started_not_connected, NodeName} | {error, boot_timeout, NodeName} | {error, init_timeout, NodeName} | {error, startup_timeout, NodeName} | {error, not_alive, NodeName}</v><v>NodeName = atom()</v></type>
<desc><marker id="start-2"/>

<p>Starts an Erlang node with name <c>Node</c> on host
   <c>Host</c> with the default options.</p>
<p><em>See also:</em> <seealso marker="#start-3">start/3</seealso>.</p>
</desc></func>
<func>
<name>start(Host, Node, Options::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}</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>Result = {ok, NodeName} | {error, already_started, NodeName} | {error, started_not_connected, NodeName} | {error, boot_timeout, NodeName} | {error, init_timeout, NodeName} | {error, startup_timeout, NodeName} | {error, not_alive, NodeName}</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> will be used
   to log in onto the remote host <c>Host</c>.
   Username, if omitted, defaults to the current user name,
   and password is empty by default.</p>
  
   <p>A list of functions specified in the <c>Startup</c> option will be
   executed after startup of the node. Note that all used modules should be
   present in the code path on the <c>Host</c>.</p>
  
   <p>The timeouts are applied as follows:
   <list>
    <item>
     <c>BootTimeout</c> - time to start the Erlang node, in seconds.
     Defaults to 3 seconds. If node does not become pingable within this time,
     the result <c>{error, boot_timeout, NodeName}</c> is returned;
    </item>
    <item>
     <c>InitTimeout</c> - time to wait for the node until it calls the
      internal callback function informing master about successfull startup.
      Defaults to one second.
      In case of timed out message the result
      <c>{error, init_timeout, NodeName}</c> is returned;
    </item>
    <item>
     <c>StartupTimeout</c> - time to wait intil the node finishes to run
      the <c>StartupFunctions</c>. Defaults to one second.
      If this timeout occurs, the result
      <c>{error, startup_timeout, NodeName}</c> is returned.
    </item>
   </list></p>
  
   <p>Option <c>monitor_master</c> specifies, if the slave node should be
   stopped in case of master node stop. Defaults to false.</p>
  
   <p>Option <c>kill_if_fail</c> specifies, if the slave node should be
   killed in case of a timeout during initialization or startup.
   Defaults to true. Note that node also may be still alive it the boot
   timeout occurred, but it will not be killed in this case.</p>
  
   <p>Option <c>erlang_flags</c> specifies, which flags will be added
   to the parameters of the <c>erl</c> executable.</p>
  
   <p>Special return values are:
   <list>
    <item><c>{error, already_started, NodeName}</c> - if the node with
     the given name is already started on a given host;</item>
    <item><c>{error, started_not_connected, NodeName}</c> - if node is
    started, but not connected to the master node.</item>
    <item><c>{error, not_alive, NodeName}</c> - if node on which the
     <c>ct_slave:start/3</c> is called, is not alive. Note that
     <c>NodeName</c> is the name of current node in this case.</item>
   </list></p>
  
</desc></func>
<func>
<name>stop(Node) -&gt; Result</name>
<fsummary>Stops the running Erlang node with name Node on
   the localhost.</fsummary>
<type>
<v>Node = atom()</v><v>Result = {ok, NodeName} | {error, not_started, NodeName} | {error, not_connected, NodeName} | {error, stop_timeout, NodeName}</v><v>NodeName = atom()</v></type>
<desc><marker id="stop-1"/>

<p>Stops the running Erlang node with name <c>Node</c> on
   the localhost.</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, not_started, NodeName} | {error, not_connected, NodeName} | {error, stop_timeout, NodeName}</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>

<authors>
<aname> </aname>
<email> </email></authors></erlref>