aboutsummaryrefslogtreecommitdiffstats
path: root/lib/common_test/doc/src/ct_slave.xml
blob: 44a7b7873f0ff8d5ac6e834cb3265fa320c82116 (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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
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) -&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>