forked from geopm/geopm.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathGEOPM_CXX_MAN_Agent.3.html
523 lines (478 loc) · 61.6 KB
/
GEOPM_CXX_MAN_Agent.3.html
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
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>geopm::Agent(3) – GEOPM agent plugin interface — GEOPM documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="_static/tabs.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script src="_static/jquery.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="geopm::Agg(3) – data aggregation functions" href="GEOPM_CXX_MAN_Agg.3.html" />
<link rel="prev" title="geopm_version(3) – GEOPM library version" href="geopm_version.3.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
GEOPM
<img src="https://geopm.github.io/images/geopm-logo-clear.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="overview.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="service.html">User Guide for GEOPM Service</a></li>
<li class="toctree-l1"><a class="reference internal" href="runtime.html">User Guide for GEOPM Runtime</a></li>
<li class="toctree-l1"><a class="reference internal" href="contrib.html">GEOPM Contributor Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="devel.html">GEOPM Developer Guide</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="reference.html">Reference Manual</a><ul class="current">
<li class="toctree-l2 current"><a class="reference internal" href="reference.html#geopm-manual-pages">GEOPM Manual Pages</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="geopm.7.html">geopm(7) – Global Extensible Open Power Manager</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio.7.html">geopm_pio(7) – GEOPM PlatformIO interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_cnl.7.html">geopm_pio_cnl(7) – Signals and controls for Compute Node Linux Board-Level Metrics</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_const_config.7.html">geopm_pio_const_config(7) – Signals for ConstConfigIOGroup</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_cpuinfo.7.html">geopm_pio_cpuinfo(7) – Signals and controls for the CPUInfoIOGroup</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_dcgm.7.html">geopm_pio_dcgm(7) – IOGroup providing signals and controls for NVIDIA GPUs</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_levelzero.7.html">geopm_pio_levelzero(7) – IOGroup providing signals and controls for Intel GPUs</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_msr.7.html">geopm_pio_msr(7) – Signals and controls for Model Specific Registers (MSRs)</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_nvml.7.html">geopm_pio_nvml(7) – IOGroup providing signals and controls for NVIDIA GPUs</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_profile.7.html">geopm_pio_profile(7) – Signals and controls for the ProfileIOGroup</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_service.7.html">geopm_pio_service(7) – Signals and controls for the ServiceIOGroup</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_sst.7.html">geopm_pio_sst(7) – Signals and controls for Intel Speed Select Technology</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_sysfs.7.html">geopm_pio_sysfs(7) – Signals and controls for sysfs attributes</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio_time.7.html">geopm_pio_time(7) – Signals and controls for Time IO Group</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmaccess.1.html">geopmaccess(1) – Access management for the GEOPM Service</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmadmin.1.html">geopmadmin(1) – tool for GEOPM system administrators</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmagent.1.html">geopmagent(1) – query agent information and create static policies</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmbench.1.html">geopmbench(1) – synthetic benchmark application</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmctl.1.html">geopmctl(1) – GEOPM runtime control application</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmendpoint.1.html">geopmendpoint(1) – command line tool for dynamic policy control</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmlaunch.1.html">geopmlaunch(1) – application launch wrapper</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmread.1.html">geopmread(1) – query platform information</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmsession.1.html">geopmsession(1) – Command line interface for the GEOPM service batch read features</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmwrite.1.html">geopmwrite(1) – modify platform state</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmdpy.7.html">geopmdpy(7) – global extensible open power manager python daemon package</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopmpy.7.html">geopmpy(7) – global extensible open power manager python package</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent.3.html">geopm_agent(3) – query information about available agents</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_ctl.3.html">geopm_ctl(3) – GEOPM runtime control thread</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_daemon.3.html">geopm_daemon(3) – helpers for GEOPM daemons</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_endpoint.3.html">geopm_endpoint(3) – dynamic policy control for resource management</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_error.3.html">geopm_error(3) – error code descriptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_field.3.html">geopm_agent(3) – query information about available agents</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_fortran.3.html">geopm_fortran(3) – GEOPM fortran interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_hash.3.html">geopm_hash(3) – helper methods for encoding</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_imbalancer.3.html">geopm_imbalancer(3) – set artificial runtime imbalance</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_pio.3.html">geopm_pio(3) – interfaces to query and modify platform</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_policystore.3.html">geopm_policystore(3) – GEOPM resource policy store interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_prof.3.html">geopm_prof(3) – application profiling interfaces</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_sched.3.html">geopm_sched(3) – interface with Linux scheduler</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_time.3.html">geopm_time(3) – helper methods for time</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_topo.3.html">geopm_topo(3) – query platform component topology</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_version.3.html">geopm_version(3) – GEOPM library version</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">geopm::Agent(3) – GEOPM agent plugin interface</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#namespaces">Namespaces</a></li>
<li class="toctree-l4"><a class="reference internal" href="#synopsis">Synopsis</a></li>
<li class="toctree-l4"><a class="reference internal" href="#description">Description</a></li>
<li class="toctree-l4"><a class="reference internal" href="#factory-accessor">Factory Accessor</a></li>
<li class="toctree-l4"><a class="reference internal" href="#class-methods">Class Methods</a></li>
<li class="toctree-l4"><a class="reference internal" href="#errors">Errors</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example">Example</a></li>
<li class="toctree-l4"><a class="reference internal" href="#see-also">See Also</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_Agg.3.html">geopm::Agg(3) – data aggregation functions</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_CNLIOGroup.3.html">geopm::CNLIOGroup(3) – IOGroup for interaction with Compute Node Linux</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_CPUActivityAgent.3.html">geopm::CPUActivityAgent(3) – agent for selecting CPU frequency based on CPU compute activity</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_CircularBuffer.3.html">geopm::CircularBuffer(3) – generic circular buffer</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_Comm.3.html">geopm::Comm(3) – communication abstractions</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_CpuinfoIOGroup.3.html">geopm::CpuinfoIOGroup(3) – IOGroup for CPU frequency limits</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_Daemon.3.html">geopm::Daemon(3) – GEOPM daemon helper methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_Endpoint.3.html">geopm::Endpoint(3) – GEOPM endpoint interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_Exception.3.html">geopm::Exception(3) – custom GEOPM exceptions</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_GPUActivityAgent.3.html">geopm::GPUActivityAgent(3) – agent for selecting GPU frequency based on GPU compute activity</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_Helper.3.html">geopm::Helper – common helper methods</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_IOGroup.3.html">geopm::IOGroup(3) – provides system values and settings</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_MPIComm.3.html">geopm::MPIComm(3) – implementation of Comm using MPI</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_MSRIO.3.html">geopm::MSRIO(3) – methods for reading and writing MSRs</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_MSRIOGroup.3.html">geopm::MSRIOGroup – IOGroup providing MSR-based signals and controls</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_MonitorAgent.3.html">geopm::MonitorAgent – agent that enforces no policies</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PlatformIO.3.html">geopm::PlatformIO(3) – GEOPM platform interface</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PlatformTopo.3.html">geopm::PlatformTopo(3) – platform topology information</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PluginFactory.3.html">geopm::PluginFactory(3) – abstract factory for plugins</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PowerBalancer.3.html">geopm::PowerBalancer(3) – balances power according to epoch runtime</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PowerBalancerAgent.3.html">geopm::PowerBalancerAgent(3) – agent optimizing performance under a power cap</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PowerGovernor.3.html">geopm::PowerGovernor(3) – enforces a power limit</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_PowerGovernorAgent.3.html">geopm::PowerGovernorAgent(3) – agent that enforces a power cap</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_ProfileIOGroup.3.html">geopm::ProfileIOGroup(3) – IOGroup providing application signals</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_SampleAggregator.3.html">geopm::SampleAggregator(3) – per-region aggregated signal data</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_SharedMemory.3.html">geopm::SharedMemory(3) – abstractions for shared memory</a></li>
<li class="toctree-l3"><a class="reference internal" href="GEOPM_CXX_MAN_TimeIOGroup.3.html">geopm::TimeIOGroup(3) – IOGroup providing time signals</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_report.7.html">geopm_report(7) – GEOPM summary report file</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_cpu_activity.7.html">geopm_agent_cpu_activity(7) – agent for selecting CPU frequency based on CPU compute activity</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_ffnet.7.html">geopm_agent_ffnet(7) – agent for adjusting frequencies based on application behavior</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_frequency_map.7.html">geopm_agent_frequency_map(7) – agent for running regions at user selected frequencies</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_gpu_activity.7.html">geopm_agent_gpu_activity(7) – agent for selecting GPU frequency based on GPU compute activity</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_monitor.7.html">geopm_agent_monitor(7) – agent implementation for aggregating statistics</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_power_balancer.7.html">geopm_agent_power_balancer(7) – agent optimizes performance under a power cap</a></li>
<li class="toctree-l3"><a class="reference internal" href="geopm_agent_power_governor.7.html">geopm_agent_power_governor(7) – agent enforces a power cap</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="reference.html#doxygen-pages">Doxygen Pages</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">GEOPM</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="reference.html">Reference Manual</a></li>
<li class="breadcrumb-item active">geopm::Agent(3) – GEOPM agent plugin interface</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/GEOPM_CXX_MAN_Agent.3.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="geopm-agent-3-geopm-agent-plugin-interface">
<h1>geopm::Agent(3) – GEOPM agent plugin interface<a class="headerlink" href="#geopm-agent-3-geopm-agent-plugin-interface" title="Permalink to this heading"></a></h1>
<section id="namespaces">
<h2>Namespaces<a class="headerlink" href="#namespaces" title="Permalink to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">Agent</span></code> class and the <code class="docutils literal notranslate"><span class="pre">agent_factory()</span></code> function are members of
the <code class="docutils literal notranslate"><span class="pre">namespace</span> <span class="pre">geopm</span></code>, but the full names, <code class="docutils literal notranslate"><span class="pre">geopm::Agent</span></code> and
<code class="docutils literal notranslate"><span class="pre">geopm::agent_factory()</span></code>, have been abbreviated in this manual.
Similarly, the <code class="docutils literal notranslate"><span class="pre">std::</span></code> namespace specifier has been omitted from the
interface definitions for the following standard types: <code class="docutils literal notranslate"><span class="pre">std::vector</span></code>,
<code class="docutils literal notranslate"><span class="pre">std::pair</span></code>, <code class="docutils literal notranslate"><span class="pre">std::string</span></code>, <code class="docutils literal notranslate"><span class="pre">std::map</span></code>, and <code class="docutils literal notranslate"><span class="pre">std::function</span></code>, to enable
better rendering of this manual.</p>
</section>
<section id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Permalink to this heading"></a></h2>
<p>#include <a class="reference external" href="https://github.com/geopm/geopm/blob/dev/src/Agent.hpp"><geopm/Agent.hpp></a></p>
<p>Link with <code class="docutils literal notranslate"><span class="pre">-lgeopm</span></code></p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">PluginFactory</span><span class="o"><</span><span class="n">Agent</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">agent_factory</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::init</span><span class="p">(</span><span class="kt">int</span><span class="w"> </span><span class="n">level</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">fan_in</span><span class="p">,</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="n">is_level_root</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::validate_policy</span><span class="p">(</span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">policy</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::split_policy</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">in_policy</span><span class="p">,</span>
<span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">>&</span><span class="w"> </span><span class="n">out_policy</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="nf">Agent::do_send_policy</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::aggregate_sample</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">in_sample</span><span class="p">,</span>
<span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">out_sample</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="nf">Agent::do_send_sample</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::adjust_platform</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">in_policy</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">bool</span><span class="w"> </span><span class="nf">Agent::do_write_batch</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::sample_platform</span><span class="p">(</span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">out_sample</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::wait</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">pair</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">report_header</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">pair</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">report_host</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="n">map</span><span class="o"><</span><span class="kt">uint64_t</span><span class="p">,</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">pair</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">report_region</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">trace_names</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">function</span><span class="o"><</span><span class="n">string</span><span class="p">(</span><span class="kt">double</span><span class="p">)</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">trace_formats</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::trace_values</span><span class="p">(</span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">values</span><span class="p">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">virtual</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::enforce_policy</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">policy</span><span class="p">)</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="k">static</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">Agent::num_policy</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">map</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">dictionary</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">Agent::num_policy</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="o">&</span><span class="n">agent_name</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">Agent::num_sample</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">map</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">dictionary</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="kt">int</span><span class="w"> </span><span class="nf">Agent::num_sample</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="o">&</span><span class="n">agent_name</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">policy_names</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">map</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">dictionary</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">policy_names</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="o">&</span><span class="n">agent_name</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">sample_names</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">map</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">dictionary</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">sample_names</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">string</span><span class="w"> </span><span class="o">&</span><span class="n">agent_name</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="n">map</span><span class="o"><</span><span class="n">string</span><span class="p">,</span><span class="w"> </span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="n">Agent</span><span class="o">::</span><span class="n">make_dictionary</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">policy_names</span><span class="p">,</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">string</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">sample_names</span><span class="p">);</span>
<span class="k">static</span><span class="w"> </span><span class="kt">void</span><span class="w"> </span><span class="nf">Agent::aggregate_sample</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">in_sample</span><span class="p">,</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="n">function</span><span class="o"><</span><span class="kt">double</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">>&</span><span class="p">)</span><span class="o">></span><span class="w"> </span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">agg_func</span><span class="p">,</span>
<span class="w"> </span><span class="n">vector</span><span class="o"><</span><span class="kt">double</span><span class="o">></span><span class="w"> </span><span class="o">&</span><span class="n">out_sample</span><span class="p">);</span>
</pre></div>
</div>
</section>
<section id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">Agent</span></code> class is an abstract pure virtual class that defines the
fundamental procedures executed by the GEOPM runtime. In general, the
Agent is responsible for making decisions about how and what control the
runtime should exert based on readings of system values. By default
the <a class="reference internal" href="geopm_agent_monitor.7.html"><span class="doc">geopm_agent_monitor(7)</span></a> is used, but other agents can be
selected with the <code class="docutils literal notranslate"><span class="pre">--geopm-agent</span></code> command line option to the
<a class="reference internal" href="geopmlaunch.1.html"><span class="doc">geopmlaunch(1)</span></a> or <code class="docutils literal notranslate"><span class="pre">GEOPM_AGENT</span></code> environment variable. Exactly
one agent type is used during each execution of the GEOPM runtime.</p>
<p>The <a class="reference internal" href="GEOPM_CXX_MAN_PluginFactory.3.html"><span class="doc">geopm::PluginFactory(3)</span></a> man page gives a general overview of
concepts related to extending GEOPM through plugins. Please refer to
that overview as an introduction before implementing an <code class="docutils literal notranslate"><span class="pre">Agent</span></code> plugin.</p>
<p>A single process (or application thread) on each compute node utilized
by an application running with GEOPM creates a <code class="docutils literal notranslate"><span class="pre">Controller</span></code> object and
each of these objects creates one or more <code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects. The
<code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects are related to each other through a balanced tree of
bi-directional communication. The “leaf” <code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects are defined
to have no children and one parent. The “tree” <code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects defined
to have many children and one Agent as the parent. The “root” Agent
objects are defined to have many children and a static policy as the parent.
Note that in some cases (e.g. a single node job execution) a “tree” Agent
may not be involved at all. The <code class="docutils literal notranslate"><span class="pre">Agent::init()</span></code> method is called by the
<code class="docutils literal notranslate"><span class="pre">Controller</span></code> prior to all other <code class="docutils literal notranslate"><span class="pre">Agent</span></code> methods. The parameters passed
by the <code class="docutils literal notranslate"><span class="pre">Controller</span></code> in this call define the geometry of the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> tree
and where the particular <code class="docutils literal notranslate"><span class="pre">Agent</span></code> object falls in the tree. See detailed
description of <code class="docutils literal notranslate"><span class="pre">Agent::init()</span></code> below for more information about the tree
structure.</p>
<p>All <code class="docutils literal notranslate"><span class="pre">Controller</span></code>s create an <code class="docutils literal notranslate"><span class="pre">Agent</span></code> object to execute <em>level</em> 0, or
“leaf” responsibilities. The leaf responsibilities include monitoring
signals and deriving samples to send to their parent <code class="docutils literal notranslate"><span class="pre">Agent</span></code>s at
<em>level</em> 1 in the tree. Additionally a leaf <code class="docutils literal notranslate"><span class="pre">Agent</span></code> must interpret
policies received from their parent agent at <em>level</em> 1 and set
controls which reflect the policy. Some of the <code class="docutils literal notranslate"><span class="pre">Controller</span></code> objects
will create <code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects to execute non-zero <em>level</em>, or “tree”
responsibilities. These non-zero <em>level</em> <code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects are
responsible for aggregating samples from child agents to send to
parent agents and splitting policy values from parent agents to send
to child agents. Note that the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> running at the root of the
tree uses the same policy/sample interface to interact with the
resource manager.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">Agent</span></code> class is designed to read signals and write controls for
the hardware and application using the <a class="reference internal" href="GEOPM_CXX_MAN_PlatformIO.3.html"><span class="doc">geopm::PlatformIO(3)</span></a>
interface. Please see the manual for details about how the
<code class="docutils literal notranslate"><span class="pre">PlatformIO</span></code> abstraction enables access to hardware capabilities,
extension of <code class="docutils literal notranslate"><span class="pre">Agent</span></code> algorithms to new hardware architectures, a
mapping of application behavior to hardware domains, and code reuse of
I/O implementations by different <code class="docutils literal notranslate"><span class="pre">Agent</span></code> classes.</p>
</section>
<section id="factory-accessor">
<h2>Factory Accessor<a class="headerlink" href="#factory-accessor" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">agent_factory()</span></code>:
This method returns the singleton accessor for the Agent factory.
Calling this method will create the factory if it does not already exist.
If this method is creating the factory, loading of the built-in Agents
will be attempted. For more information see <a class="reference internal" href="GEOPM_CXX_MAN_PluginFactory.3.html"><span class="doc">geopm::PluginFactory(3)</span></a>.</p></li>
</ul>
</section>
<section id="class-methods">
<h2>Class Methods<a class="headerlink" href="#class-methods" title="Permalink to this heading"></a></h2>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">init()</span></code>:
The <code class="docutils literal notranslate"><span class="pre">init()</span></code> method is the first method that will be called and
provides contextual information for the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> about the
communication tree geometry and where in the tree the <code class="docutils literal notranslate"><span class="pre">Agent</span></code>
resides. The communication tree that connects the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> objects
is a balanced tree. The <em>level</em> is the minimum number of edges
between <code class="docutils literal notranslate"><span class="pre">self</span></code> and any leaf <code class="docutils literal notranslate"><span class="pre">Agent</span></code>. Only when <em>level</em> is zero
will the <code class="docutils literal notranslate"><span class="pre">sample_platform()</span></code> and <code class="docutils literal notranslate"><span class="pre">adjust_platform()</span></code> methods be
called. If the <em>level</em> is zero then the <code class="docutils literal notranslate"><span class="pre">init()</span></code> method should
push all signals and controls for <a class="reference internal" href="GEOPM_CXX_MAN_PlatformIO.3.html"><span class="doc">PlatformIO(3)</span></a>.
The <em>fan_in</em> is a vector indexed by <em>level</em> that describes the number of
siblings that an <code class="docutils literal notranslate"><span class="pre">Agent</span></code> at <em>level</em> has which share a parent. The
figure below represents a tree with <code class="docutils literal notranslate"><span class="pre">fan_in</span> <span class="pre">==</span> <span class="pre">{4,3,2}</span></code> where each
<code class="docutils literal notranslate"><span class="pre">Agent</span></code> is signified by a digit that is equal to the <em>level</em>. Note
that this example supports 24 compute nodes. The <em>is_level_root</em>
parameter is true for one child of each parent and only if this
parameter is true will the controller call the <code class="docutils literal notranslate"><span class="pre">ascend()</span></code> or
<code class="docutils literal notranslate"><span class="pre">descend()</span></code> methods of the object.</p></li>
</ul>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="p">(</span><span class="mi">3</span><span class="p">)</span>
<span class="n">___________</span><span class="o">/</span> \<span class="n">____________</span>
<span class="o">/</span> \
<span class="n">__</span> <span class="p">(</span><span class="mi">2</span><span class="p">)</span> <span class="n">_</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span><span class="n">__</span>
<span class="n">_______</span><span class="o">/</span> <span class="o">/</span> \<span class="n">_____</span> <span class="n">_____</span><span class="o">/</span> <span class="o">|</span> \<span class="n">_______</span>
<span class="o">/</span> <span class="o">|</span> \ <span class="o">/</span> <span class="o">|</span> \
<span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span> <span class="o">--</span>
<span class="o">/</span> <span class="o">|</span> \ <span class="o">/</span> <span class="o">|</span> \ <span class="o">/</span> <span class="o">|</span> \ <span class="o">/</span> <span class="o">|</span> \ <span class="o">/</span> <span class="o">|</span> \ <span class="o">/</span> <span class="o">|</span> \
<span class="p">(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="o">|</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="o">|</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="o">|</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)</span> <span class="p">(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="o">|</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="o">|</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="o">|</span><span class="mi">0</span><span class="p">)(</span><span class="mi">0</span><span class="p">)</span>
</pre></div>
</div>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">validate_policy()</span></code>:
Called by user of Agent class to validate incoming policy values and
replace NaNs with defaults. If a value of <em>policy</em> is not NaN but the
value is not supported by the Agent the method will throw a <code class="docutils literal notranslate"><span class="pre">geopm::Exception</span></code>
with error code <code class="docutils literal notranslate"><span class="pre">GEOPM_ERROR_INVALID</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">split_policy()</span></code>:
Split policy for children at next level down the tree. The
<em>in_policy</em> is an input vector of policy values from the parent.
The <em>out_policy</em> is an output vector of policies to be sent to
each child.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">do_send_policy()</span></code>:
Used to indicate to the Controller whether to send the output
from <code class="docutils literal notranslate"><span class="pre">split_policy()</span></code> down the tree to the Agent’s children.
Returns true if the policy has been updated since the last call.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">aggregate_sample()</span></code>:
Aggregate samples from children for the next level up the tree.
The <em>in_sample</em> parameter is a vector of sample vectors, one
sample vector from each child. The samples from a given index
in the input vectors are transformed to a single value at the
same index in the output. The <em>out_sample</em> is an output vector
of aggregated sample values to be sent up to the parent.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">do_send_sample()</span></code>:
Used to indicate to the Controller whether to send the output from
<code class="docutils literal notranslate"><span class="pre">aggregate_sample()</span></code> up the tree to the Agent’s parent. Returns
true if any samples have been updated since the last call.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">adjust_platform()</span></code>:
Adjust the platform settings based on the policy from above.
Settings for each control are in the <em>in_policy</em>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">do_write_batch()</span></code>:
Used to indicate to the Controller whether to call
<code class="docutils literal notranslate"><span class="pre">PlatformIO::write_batch()</span></code> to enact new control values on the
platform. Returns true if any control values have been updated
since the last call.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sample_platform()</span></code>:
Read signals from the platform and interpret/aggregate these
signals to create a sample which can be sent up the tree. The
<em>out_sample</em> parameter is an output vector of agent specific sample
values to be sent up the tree. Returns true if the sample has been
updated since the last call.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">wait()</span></code>:
Called to wait for the sample period to elapse. This controls the
cadence of the Controller main loop.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">report_header()</span></code>:
Custom fields that will be added to the report header when this
agent is used. To be consistent with the rest of the header, the
keys should be title case, e.g. <code class="docutils literal notranslate"><span class="pre">"Agent</span> <span class="pre">Header</span> <span class="pre">Name"</span></code>; they must not
contain the colon character <code class="docutils literal notranslate"><span class="pre">':'</span></code>. Care must be taken not to add
keys that conflict with default header keys, like names that start
with <code class="docutils literal notranslate"><span class="pre">"Start</span> <span class="pre">Time"</span></code>, <code class="docutils literal notranslate"><span class="pre">"Profile"</span></code>, <code class="docutils literal notranslate"><span class="pre">"Agent"</span></code> or <code class="docutils literal notranslate"><span class="pre">"Policy"</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">report_host()</span></code>:
Custom fields for the Host section of the report. To be
consistent with the rest of this section, the keys should have
the first letter capitalized, e.g. <code class="docutils literal notranslate"><span class="pre">"Final</span> <span class="pre">freq</span> <span class="pre">map"</span></code>; they must
not contain the colon character <code class="docutils literal notranslate"><span class="pre">':'</span></code>. Care must be taken not to
add keys that conflict with default host keys, like names that
start with <code class="docutils literal notranslate"><span class="pre">"Region"</span></code>, <code class="docutils literal notranslate"><span class="pre">"Epoch</span> <span class="pre">Totals"</span></code> or <code class="docutils literal notranslate"><span class="pre">"Application</span> <span class="pre">Totals"</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">report_region()</span></code>:
Custom fields for each region in the report. To be consistent
with the rest of the region report, the string keys that will
appear at the start of each line should be all lower case with
words separated by hyphens and followed by the units if
applicable, e.g <code class="docutils literal notranslate"><span class="pre">"package-energy</span> <span class="pre">(joules)"</span></code>. The field name must
not contain the colon character <code class="docutils literal notranslate"><span class="pre">':'</span></code>. Care must be taken not to
add keys that conflict with the default region keys, like names
that start with <code class="docutils literal notranslate"><span class="pre">"runtime"</span></code>, <code class="docutils literal notranslate"><span class="pre">"sync-runtime"</span></code>, <code class="docutils literal notranslate"><span class="pre">"package-energy"</span></code>,
<code class="docutils literal notranslate"><span class="pre">"dram-energy"</span></code>, <code class="docutils literal notranslate"><span class="pre">"power"</span></code>, <code class="docutils literal notranslate"><span class="pre">"frequency"</span></code>, <code class="docutils literal notranslate"><span class="pre">"network-time"</span></code>, or <code class="docutils literal notranslate"><span class="pre">"count"</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">trace_names()</span></code>:
Column headers to be added to the trace. These will be
automatically converted to lower case. The header names must
not contain the pipe character <code class="docutils literal notranslate"><span class="pre">'|'</span></code> or whitespace.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">trace_formats()</span></code>:
Returns format string for each column added to the trace</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">trace_values()</span></code>:
Called by Controller to get latest values to be added to the trace.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">enforce_policy()</span></code>:
Enforce the policy one time with
<code class="docutils literal notranslate"><span class="pre">PlatformIO::write_control()</span></code>. Called to enforce
static policies in the absence of a Controller.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">num_policy()</span></code>:
Used to look up the number of values in the policy vector sent
down the tree for a specific type of <code class="docutils literal notranslate"><span class="pre">Agent</span></code>. This should be
called with the <em>dictionary</em> returned by
<code class="docutils literal notranslate"><span class="pre">agent_factory().dictionary(agent_name)</span></code> for the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> of
interest.
Also has an overloaded version which takes the <em>agent_name</em>.
Note this is a static helper function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">num_sample()</span></code>:
Used to look up the number of values in the sample vector sent up
the tree for a specific type of <code class="docutils literal notranslate"><span class="pre">Agent</span></code>. This should be called
with the dictionary returned by
<code class="docutils literal notranslate"><span class="pre">agent_factory().dictionary(agent_name)</span></code> for the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> of
interest.
Also has an overloaded version which takes the <em>agent_name</em>.
Note this is a static helper function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">policy_names()</span></code>:
Used to look up the names of values in the policy vector sent down
the tree for a specific type of <code class="docutils literal notranslate"><span class="pre">Agent</span></code>. This should be called
with the dictionary returned by
<code class="docutils literal notranslate"><span class="pre">agent_factory().dictionary(agent_name)</span></code> for the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> of
interest.
Also has an overloaded version which takes the <em>agent_name</em>.
Note this is a static helper function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sample_names()</span></code>:
Used to look up the names of values in the sample vector sent up
the tree for a specific of <code class="docutils literal notranslate"><span class="pre">Agent</span></code>. This should be called with the
dictionary returned by
<code class="docutils literal notranslate"><span class="pre">agent_factory().dictionary(agent_name)</span></code> for the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> of
interest.
Also has an overloaded version which takes the <em>agent_name</em>.
Note this is a static helper function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">make_dictionary()</span></code>:
Used to create a correctly formatted dictionary for an <code class="docutils literal notranslate"><span class="pre">Agent</span></code> at
the time the <code class="docutils literal notranslate"><span class="pre">Agent</span></code> is registered with the factory. Concrete
<code class="docutils literal notranslate"><span class="pre">Agent`</span></code> classes may provide <code class="docutils literal notranslate"><span class="pre">policy_names()</span></code> and <code class="docutils literal notranslate"><span class="pre">sample_names()</span></code>
methods to provide the vectors to be passed to this method. Note
this is a static helper function.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">aggregate_sample()</span></code>:
Generically aggregate a vector of samples given a vector of
aggregation functions. This helper method applies a different
aggregation function to each sample element while aggregating
across child samples. The <em>in_sample</em> parameter is an input vector
over children of the sample vector received from each child. The
<em>agg_func</em> is an input vector over agent samples of the
aggregation function that is applied. The <em>out_sample</em> is an
output sample vector resulting from the applying the aggregation
across child samples. Note this is a static helper function.</p></li>
</ul>
</section>
<section id="errors">
<h2>Errors<a class="headerlink" href="#errors" title="Permalink to this heading"></a></h2>
<p>All functions described on this man page throw <a class="reference internal" href="GEOPM_CXX_MAN_Exception.3.html"><span class="doc">geopm::Exception(3)</span></a>
on error.</p>
</section>
<section id="example">
<h2>Example<a class="headerlink" href="#example" title="Permalink to this heading"></a></h2>
<p>Please see the <a class="reference external" href="https://github.com/geopm/geopm/tree/dev/tutorial/agent">Agent tutorial</a> for more
information. This code is located in the GEOPM source under tutorial/agent.</p>
</section>
<section id="see-also">
<h2>See Also<a class="headerlink" href="#see-also" title="Permalink to this heading"></a></h2>
<p><a class="reference internal" href="geopm.7.html"><span class="doc">geopm(7)</span></a></p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="geopm_version.3.html" class="btn btn-neutral float-left" title="geopm_version(3) – GEOPM library version" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="GEOPM_CXX_MAN_Agg.3.html" class="btn btn-neutral float-right" title="geopm::Agg(3) – data aggregation functions" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2015 - 2023, Intel Corporation. All rights reserved..</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>