1 /* -*- Mode: C; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ 2 /* 3 * Copyright (C) 2008 Kouhei Sutou <kou@cozmixng.org> 4 * 5 * This library is free software: you can redistribute it and/or modify 6 * it under the terms of the GNU Lesser General Public License as published by 7 * the Free Software Foundation, either version 3 of the License, or 8 * (at your option) any later version. 9 * 10 * This library is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with this program. If not, see <http://www.gnu.org/licenses/>. 17 * 18 */ 19 20 #ifndef __CUT_MULTI_PROCESS_H__ 21 #define __CUT_MULTI_PROCESS_H__ 22 23 #include <cutter/cut-types.h> 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * SECTION: cut-multi-process 31 * @title: Multi Process 32 * @short_description: Utilities to run your tests on multi 33 * processes. 34 * 35 * If your test target supports multi-process and/or 36 * multi-thread, you need to test them. You can use 37 * #CutSubProcess and #CutSubProcessGroup to do it. 38 * 39 * #CutSubProcess runs your test on another process and 40 * forwards results of it to a test on your main 41 * process. You will get results of test on another process 42 * as results of test on your main process. 43 * 44 * #CutSubProcessGroup is a convenience object to run some 45 * #CutSubProcess. 46 * 47 * Since: 1.0.4 48 */ 49 50 /** 51 * CutSubProcess: 52 * 53 * An object to represent sub cutter process. It contains 54 * sub cutter process's parameters and results of sub cutter 55 * process. 56 * 57 * e.g.: 58 * |[ 59 * CutSubProcess *sub_process; 60 * 61 * sub_process = cut_take_new_sub_process("test-dir"); 62 * cut_sub_process_set_multi_thread(sub_process, TRUE); 63 * cut_assert_true(cut_sub_process_run(sub_process)); 64 * ]| 65 * 66 * Since: 1.0.4 67 */ 68 typedef struct _CutSubProcess CutSubProcess; 69 70 /** 71 * CutSubProcessGroup: 72 * 73 * An object to run sub cutter processes. This is just for 74 * convenience. 75 * 76 * e.g.: 77 * |[ 78 * CutSubProcess *sub_process1, *sub_process2, *sub_process3; 79 * CutSubProcessGroup *group; 80 * 81 * sub_process1 = cut_take_new_sub_process("test-dir1"); 82 * sub_process2 = cut_take_new_sub_process("test-dir2"); 83 * sub_process3 = cut_take_new_sub_process("test-dir3"); 84 * 85 * group = cut_take_new_sub_process_group(); 86 * cut_sub_process_group_add(group, sub_process1); 87 * cut_sub_process_group_add(group, sub_process2); 88 * cut_sub_process_group_add(group, sub_process3); 89 * cut_assert_true(cut_sub_process_group_run(group)); 90 * ]| 91 * 92 * Since: 1.0.4 93 */ 94 typedef struct _CutSubProcessGroup CutSubProcessGroup; 95 96 /** 97 * cut_take_new_sub_process: 98 * @test_directory: a directory includes sub process test. 99 * 100 * Creates sub cutter process that runs tests under 101 * @test_directory and returns it. A created sub process 102 * is owned by Cutter. 103 * 104 * Returns: a #CutSubProcess. 105 * 106 * Since: 1.0.4 107 */ 108 #define cut_take_new_sub_process(test_directory) \ 109 cut_utils_take_new_sub_process(test_directory, \ 110 cut_get_current_test_context()) 111 112 /** 113 * cut_sub_process_run: 114 * @sub_process: a #CutSubProcess. 115 * 116 * Runs sub cutter process. 117 * 118 * Returns: %CUT_TRUE if @sub_process is completed 119 * successfully, %CUT_FALSE otherwise. 120 * 121 * Since: 1.0.4 122 */ 123 cut_boolean cut_sub_process_run (CutSubProcess *sub_process); 124 125 /** 126 * cut_sub_process_run_async: 127 * @sub_process: a #CutSubProcess. 128 * 129 * Runs sub cutter process asynchronously. The result of 130 * @sub_process can be gotten by cut_sub_process_wait(). 131 * 132 * Since: 1.0.4 133 */ 134 void cut_sub_process_run_async (CutSubProcess *sub_process); 135 136 /** 137 * cut_sub_process_wait: 138 * @sub_process: a #CutSubProcess. 139 * 140 * Waits for sub cutter process that is ran asynchronously 141 * to complete and returns the result. 142 * 143 * Returns: %CUT_TRUE if @sub_process is completed 144 * successfully, %CUT_FALSE otherwise. 145 * 146 * Since: 1.0.4 147 */ 148 cut_boolean cut_sub_process_wait (CutSubProcess *sub_process); 149 150 /** 151 * cut_sub_process_is_success: 152 * @sub_process: a #CutSubProcess. 153 * 154 * Returns whether @sub_process is completed successfully or 155 * not. 156 * 157 * Returns: %CUT_TRUE if @sub_process is completed 158 * successfully, %CUT_FALSE otherwise. 159 * 160 * Since: 1.0.4 161 */ 162 cut_boolean cut_sub_process_is_success (CutSubProcess *sub_process); 163 164 /** 165 * cut_sub_process_is_running: 166 * @sub_process: a #CutSubProcess. 167 * 168 * Returns whether @sub_process is running or not. 169 * 170 * Returns: %CUT_TRUE if @sub_process is running, %CUT_FALSE 171 * otherwise. 172 * 173 * Since: 1.0.4 174 */ 175 cut_boolean cut_sub_process_is_running (CutSubProcess *sub_process); 176 177 /** 178 * cut_sub_process_get_test_directory: 179 * @sub_process: a #CutSubProcess. 180 * 181 * Returns a test directory that has tests to be ran. 182 * 183 * Returns: a test directory. 184 * 185 * Since: 1.0.4 186 */ 187 const char *cut_sub_process_get_test_directory (CutSubProcess *sub_process); 188 189 /** 190 * cut_sub_process_set_test_directory: 191 * @sub_process: a #CutSubProcess. 192 * @test_directory: a test directory. 193 * 194 * Sets @test_directory as a test directory that has tests 195 * to be ran. This is same as TEST_DIRECTORY required 196 * command line argument. 197 * 198 * Since: 1.0.4 199 */ 200 void cut_sub_process_set_test_directory (CutSubProcess *sub_process, 201 const char *test_directory); 202 203 /** 204 * cut_sub_process_get_source_directory: 205 * @sub_process: a #CutSubProcess. 206 * 207 * Returns a source directory that has source files. 208 * 209 * Returns: a source directory. 210 * 211 * Since: 1.0.4 212 */ 213 const char *cut_sub_process_get_source_directory 214 (CutSubProcess *sub_process); 215 216 /** 217 * cut_sub_process_set_source_directory: 218 * @sub_process: a #CutSubProcess. 219 * @source_directory: a source directory. 220 * 221 * Sets @source_directory as a source directory that has 222 * source files. This is same as --source-directory command 223 * line option. 224 * 225 * Since: 1.0.4 226 */ 227 void cut_sub_process_set_source_directory 228 (CutSubProcess *sub_process, 229 const char *source_directory); 230 231 /** 232 * cut_sub_process_get_multi_thread: 233 * @sub_process: a #CutSubProcess. 234 * 235 * Returns whether @sub_process is ran in multi-thread mode. 236 * 237 * Returns: %CUT_TRUE if @sub_process is ran in multi-thread 238 * mode, %CUT_FALSE otherwise. 239 * 240 * Since: 1.0.4 241 */ 242 cut_boolean cut_sub_process_get_multi_thread (CutSubProcess *sub_process); 243 244 /** 245 * cut_sub_process_set_multi_thread: 246 * @sub_process: a #CutSubProcess. 247 * @multi_thread: %CUT_TRUE to be ran in multi-thread mode. 248 * 249 * Sets whether @sub_process is ran in multi-thread mode or 250 * not. This is same as --multi-thread command line option. 251 * 252 * Since: 1.0.4 253 */ 254 void cut_sub_process_set_multi_thread (CutSubProcess *sub_process, 255 cut_boolean multi_thread); 256 257 /** 258 * cut_sub_process_get_max_threads: 259 * @sub_process: a #CutSubProcess. 260 * 261 * Returns how many threads are used concurrently at a 262 * maximum in @sub_process. 263 * 264 * Returns: max number of threads used concurrently at a 265 * maximum in @sub_process. 266 * 267 * Since: 1.0.5 268 */ 269 int cut_sub_process_get_max_threads (CutSubProcess *sub_process); 270 271 /** 272 * cut_sub_process_set_max_threads: 273 * @sub_process: a #CutSubProcess. 274 * @max_threads: max number of threads used concurrently at 275 * a maximum. 276 * 277 * Sets how many threads are used concurrently at a 278 * maximum in @sub_process. -1 means no limit. This is same 279 * as --max-threads command line option. 280 * 281 * Since: 1.0.5 282 */ 283 void cut_sub_process_set_max_threads (CutSubProcess *sub_process, 284 int max_threads); 285 286 /** 287 * cut_sub_process_get_exclude_files: 288 * @sub_process: a #CutSubProcess. 289 * 290 * Returns file names that are excluded from target test 291 * files. 292 * 293 * Returns: file names that are excluded from target test files. 294 * 295 * Since: 1.0.4 296 */ 297 const char **cut_sub_process_get_exclude_files (CutSubProcess *sub_process); 298 299 /** 300 * cut_sub_process_set_exclude_files: 301 * @sub_process: a #CutSubProcess. 302 * @files: file names that are excluded from target test 303 * files. 304 * 305 * Sets file names that are excluded from target test files. 306 * This is same as --exclude-file command line option. 307 * 308 * Since: 1.0.4 309 */ 310 void cut_sub_process_set_exclude_files (CutSubProcess *sub_process, 311 const char **files); 312 313 /** 314 * cut_sub_process_get_exclude_directories: 315 * @sub_process: a #CutSubProcess. 316 * 317 * Returns directory names that are excluded from target 318 * test directories. 319 * 320 * Returns: directory names that are excluded from target 321 * test directories. 322 * 323 * Since: 1.0.4 324 */ 325 const char **cut_sub_process_get_exclude_directories 326 (CutSubProcess *sub_process); 327 328 /** 329 * cut_sub_process_set_exclude_directories: 330 * @sub_process: a #CutSubProcess. 331 * @directories: directory names that are excluded from 332 * target test directories. 333 * 334 * Sets directory names that are excluded from target test 335 * directories. This is same as --exclude-directory command line 336 * option. 337 * 338 * Since: 1.0.4 339 */ 340 void cut_sub_process_set_exclude_directories 341 (CutSubProcess *sub_process, 342 const char **directories); 343 344 /** 345 * cut_sub_process_get_target_test_case_names: 346 * @sub_process: a #CutSubProcess. 347 * 348 * Returns test case names that are ran. 349 * 350 * Returns: test case names that are ran. 351 * 352 * Since: 1.0.4 353 */ 354 const char **cut_sub_process_get_target_test_case_names 355 (CutSubProcess *sub_process); 356 357 /** 358 * cut_sub_process_set_target_test_case_names: 359 * @sub_process: a #CutSubProcess. 360 * @names: test case names that are ran. 361 * 362 * Sets test case names that are ran. This is same as 363 * --test-case command line option. 364 * 365 * Since: 1.0.4 366 */ 367 void cut_sub_process_set_target_test_case_names 368 (CutSubProcess *sub_process, 369 const char **names); 370 371 /** 372 * cut_sub_process_get_target_test_names: 373 * @sub_process: a #CutSubProcess. 374 * 375 * Returns test names that are ran. 376 * 377 * Returns: test names that are ran. 378 * 379 * Since: 1.0.4 380 */ 381 const char **cut_sub_process_get_target_test_names 382 (CutSubProcess *sub_process); 383 384 /** 385 * cut_sub_process_set_target_test_names: 386 * @sub_process: a #CutSubProcess. 387 * @names: test names that are ran. 388 * 389 * Sets test names that are ran. This is same as --test 390 * command line option. 391 * 392 * Since: 1.0.4 393 */ 394 void cut_sub_process_set_target_test_names 395 (CutSubProcess *sub_process, 396 const char **names); 397 398 /** 399 * cut_sub_process_get_elapsed: 400 * @sub_process: a #CutSubProcess. 401 * 402 * Gets the time while @sub_process was running. 403 * 404 * Returns: the time while @sub_process was running. 405 * 406 * Since: 1.0.4 407 */ 408 double cut_sub_process_get_elapsed (CutSubProcess *sub_process); 409 410 /** 411 * cut_sub_process_get_total_elapsed: 412 * @sub_process: a #CutSubProcess. 413 * 414 * Gets the sum of times that are used by each test. 415 * 416 * Returns: the sum of times that are used by each test. 417 * 418 * Since: 1.0.4 419 */ 420 double cut_sub_process_get_total_elapsed (CutSubProcess *sub_process); 421 422 /** 423 * cut_sub_process_is_crashed: 424 * @sub_process: a #CutSubProcess. 425 * 426 * Returns whether @sub_process was crashed or not. 427 * 428 * Returns: %CUT_TRUE if @sub_process was crashed, %CUT_FALSE 429 * otherwise. 430 * 431 * Since: 1.0.4 432 */ 433 cut_boolean cut_sub_process_is_crashed (CutSubProcess *sub_process); 434 435 /** 436 * cut_sub_process_get_fatal_failures: 437 * @sub_process: a #CutSubProcess. 438 * 439 * Returns whether @sub_process is ran in fatal-failures 440 * mode. See cut_sub_process_set_fatal_failures() more 441 * details of fatal-failures mode. 442 * 443 * Returns: %CUT_TRUE if @sub_process is ran in fatal-failures 444 * mode, %CUT_FALSE otherwise. 445 * 446 * Since: 1.0.4 447 */ 448 cut_boolean cut_sub_process_get_fatal_failures (CutSubProcess *sub_process); 449 450 /** 451 * cut_sub_process_set_fatal_failures: 452 * @sub_process: a #CutSubProcess. 453 * @fatal_failures: %CUT_TRUE to be ran in fatal-failures mode. 454 * 455 * Sets whether @sub_process is ran in fatal-failures mode or 456 * not. In this mode, all failures are treated as fatal 457 * problems. It means that test is aborted on failure. On 458 * some environments, breakpoint is set. 459 * 460 * This is same as --fatal-failures command line option. 461 * 462 * Since: 1.0.4 463 */ 464 void cut_sub_process_set_fatal_failures (CutSubProcess *sub_process, 465 cut_boolean fatal_failures); 466 467 /** 468 * cut_take_new_sub_process_group: 469 * 470 * Creates a group of sub cutter process. A created group 471 * is owned by Cutter. 472 * 473 * Returns: a #CutSubProcessGroup. 474 * 475 * Since: 1.0.4 476 */ 477 #define cut_take_new_sub_process_group() \ 478 cut_utils_take_new_sub_process_group(cut_get_current_test_context()) 479 480 /** 481 * cut_sub_process_group_add: 482 * @group: a #CutSubProcessGroup. 483 * @sub_process: a #CutSubProcess. 484 * 485 * Adds @sub_process to @group. 486 * 487 * Since: 1.0.4 488 */ 489 void cut_sub_process_group_add (CutSubProcessGroup *group, 490 CutSubProcess *sub_process); 491 492 /** 493 * cut_sub_process_group_run: 494 * @group: a #CutSubProcessGroup. 495 * 496 * Runs all sub cutter processes of @group and returns the 497 * result of them. 498 * 499 * Returns: %CUT_TRUE if all sub cutter processes of @group 500 * are completed successfully, %CUT_FALSE otherwise. 501 * 502 * Since: 1.0.4 503 */ 504 cut_boolean cut_sub_process_group_run (CutSubProcessGroup *group); 505 506 /** 507 * cut_sub_process_group_run_async: 508 * @group: a #CutSubProcessGroup. 509 * 510 * Runs all sub cutter processes of @group 511 * asynchronously. The result of them can be gotten by 512 * cut_sub_process_group_wait(). 513 * 514 * Since: 1.0.4 515 */ 516 void cut_sub_process_group_run_async (CutSubProcessGroup *group); 517 518 /** 519 * cut_sub_process_group_wait: 520 * @group: a #CutSubProcessGroup. 521 * 522 * Waits for all sub cutter processes of @group that are ran 523 * asynchronously to complete and returns the result. 524 * 525 * Returns: %CUT_TRUE if all sub cutter processes of @group 526 * are completed successfully, %CUT_FALSE otherwise. 527 * 528 * Since: 1.0.4 529 */ 530 cut_boolean cut_sub_process_group_wait (CutSubProcessGroup *group); 531 532 533 #ifdef __cplusplus 534 } 535 #endif 536 537 #endif /* __CUT_MULTI_PROCESS_H__ */ 538 539 /* 540 vi:nowrap:ai:expandtab:sw=4 541 */ 542