1 /**
2 * Copyright 2020-2022 Huawei Technologies Co., Ltd
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 #ifndef MINDSPORE_CCSRC_MINDDATA_DATASET_INCLUDE_DATASET_CONFIG_H
18 #define MINDSPORE_CCSRC_MINDDATA_DATASET_INCLUDE_DATASET_CONFIG_H
19
20 #include <cstdint>
21 #include <string>
22 #include <vector>
23
24 #include "include/api/dual_abi_helper.h"
25 #include "include/api/types.h"
26
27 namespace mindspore {
28 namespace dataset {
29 // Config operations for setting and getting the configuration.
30 namespace config {
31 /// \brief A function to set the seed to be used in any random generator. This is used to produce deterministic results.
32 /// \param[in] seed The default seed to be used.
33 /// \return The seed is set successfully or not.
34 /// \par Example
35 /// \code
36 /// // Set a new global configuration value for the seed value.
37 /// // Operations with randomness will use the seed value to generate random values.
38 /// bool rc = config::set_seed(5);
39 /// \endcode
40 bool DATASET_API set_seed(int32_t seed);
41
42 /// \brief A function to get the seed.
43 /// \return The seed set in the configuration.
44 /// \par Example
45 /// \code
46 /// // Get the global configuration of seed.
47 /// // If set_seed() is never called before, the default value(std::mt19937::default_seed) will be returned.
48 /// uint32_t seed = config::get_seed();
49 /// \endcode
50 uint32_t DATASET_API get_seed();
51
52 /// \brief A function to set the number of rows to be prefetched.
53 /// \param[in] prefetch_size Total number of rows to be prefetched.
54 /// \return The prefetch size is set successfully or not.
55 /// \par Example
56 /// \code
57 /// // Set a new global configuration value for the prefetch size.
58 /// bool rc = config::set_prefetch_size(1000);
59 /// \endcode
60 bool DATASET_API set_prefetch_size(int32_t prefetch_size);
61
62 /// \brief A function to get the prefetch size in number of rows.
63 /// \return Total number of rows to be prefetched.
64 /// \par Example
65 /// \code
66 /// // Get the global configuration of prefetch size.
67 /// // If set_prefetch_size() is never called before, the default value(16) will be returned.
68 /// int32_t prefetch_size = config::get_prefetch_size();
69 /// \endcode
70 int32_t DATASET_API get_prefetch_size();
71
72 /// \brief A function to set the default number of parallel workers.
73 /// \param[in] num_parallel_workers Number of parallel workers to be used as the default for each operation.
74 /// \return The workers is set successfully or not.
75 /// \par Example
76 /// \code
77 /// // Set a new global configuration value for the number of parallel workers.
78 /// // Now parallel dataset operations will run with 16 workers.
79 /// bool rc = config::set_num_parallel_workers(16);
80 /// \endcode
81 bool DATASET_API set_num_parallel_workers(int32_t num_parallel_workers);
82
83 /// \brief A function to get the default number of parallel workers.
84 /// \return Number of parallel workers to be used as the default for each operation.
85 /// \par Example
86 /// \code
87 /// // Get the global configuration of parallel workers.
88 /// // If set_num_parallel_workers() is never called before, the default value(8) will be returned.
89 /// int32_t parallel_workers = config::get_num_parallel_workers();
90 /// \endcode
91 int32_t DATASET_API get_num_parallel_workers();
92
93 /// \brief A function to set the default interval (in milliseconds) for monitor sampling.
94 /// \param[in] interval Interval (in milliseconds) to be used for performance monitor sampling.
95 /// \return The sampling interval is set successfully or not.
96 /// \par Example
97 /// \code
98 /// // Set a new global configuration value for the monitor sampling interval.
99 /// bool rc = config::set_monitor_sampling_interval(100);
100 /// \endcode
101 bool DATASET_API set_monitor_sampling_interval(int32_t interval);
102
103 /// \brief A function to get the default interval of performance monitor sampling.
104 /// \return Interval (in milliseconds) for performance monitor sampling.
105 /// \par Example
106 /// \code
107 /// // Get the global configuration of monitor sampling interval.
108 /// // If set_monitor_sampling_interval() is never called before, the default value(1000) will be returned.
109 /// int32_t sampling_interval = config::get_monitor_sampling_interval();
110 /// \endcode
111 int32_t DATASET_API get_monitor_sampling_interval();
112
113 /// \brief A function to set the default timeout (in seconds) for DSWaitedCallback. In case of a deadlock, the wait
114 /// function will exit after the timeout period.
115 /// \param[in] timeout Timeout (in seconds) to be used to end the wait in DSWaitedCallback in case of a deadlock.
116 /// \return The callback timeout is set successfully or not.
117 /// \par Example
118 /// \code
119 /// // Set a new global configuration value for the timeout value.
120 /// bool rc = config::set_callback_timeout(100);
121 /// \endcode
122 bool DATASET_API set_callback_timeout(int32_t timeout);
123
124 /// \brief A function to get the default timeout for DSWaitedCallback. In case of a deadback, the wait function
125 /// will exit after the timeout period.
126 /// \return The duration in seconds.
127 /// \par Example
128 /// \code
129 /// // Get the global configuration of callback timeout.
130 /// // If set_callback_timeout() is never called before, the default value(60) will be returned.
131 /// int32_t callback_timeout = config::get_callback_timeout();
132 /// \endcode
133 int32_t DATASET_API get_callback_timeout();
134
135 /// \brief A function to load the configuration from a file.
136 /// \param[in] file Path of the configuration file to be loaded.
137 /// \return The config file is loaded successfully or not.
138 /// \note The reason for using this API is that std::string will be constrained by the
139 /// compiler option '_GLIBCXX_USE_CXX11_ABI' while char is free of this restriction.
140 /// Check API `mindspore::dataset::config::load(const std::string &file)` and find more usage.
141 bool DATASET_API load(const std::vector<char> &file);
142
143 /// \brief A function to load the configuration from a file.
144 /// \param[in] file Path of the configuration file to be loaded.
145 /// \return The config file is loaded successfully or not.
146 /// \par Example
147 /// \code
148 /// // Set new default configuration according to values in the configuration file.
149 /// // example config file:
150 /// // {
151 /// // "logFilePath": "/tmp",
152 /// // "numParallelWorkers": 4,
153 /// // "seed": 5489,
154 /// // "monitorSamplingInterval": 30
155 /// // }
156 /// std::string config_file = "/path/to/config/file";
157 /// bool rc = config::load(config_file);
158 /// \endcode
load(const std::string & file)159 inline bool DATASET_API load(const std::string &file) { return load(StringToChar(file)); }
160 } // namespace config
161 } // namespace dataset
162 } // namespace mindspore
163 #endif // MINDSPORE_CCSRC_MINDDATA_DATASET_INCLUDE_DATASET_CONFIG_H
164