Multi Process

## Multi Process Multi Process — Utilities to run your tests on multi processes. |

## Synopsis

                        CutSubProcess;
                        CutSubProcessGroup;
    CutSubProcess *     cut_take_new_sub_process            (const char *test_directory);
    cut_boolean         cut_sub_process_run                 (CutSubProcess *sub_process);
    void                cut_sub_process_run_async           (CutSubProcess *sub_process);
    cut_boolean         cut_sub_process_wait                (CutSubProcess *sub_process);
    cut_boolean         cut_sub_process_is_success          (CutSubProcess *sub_process);
    cut_boolean         cut_sub_process_is_running          (CutSubProcess *sub_process);
    const char *        cut_sub_process_get_test_directory  (CutSubProcess *sub_process);
    void                cut_sub_process_set_test_directory  (CutSubProcess *sub_process,
                                                             const char *test_directory);
    const char *        cut_sub_process_get_source_directory
                                                            (CutSubProcess *sub_process);
    void                cut_sub_process_set_source_directory
                                                            (CutSubProcess *sub_process,
                                                             const char *source_directory);
    cut_boolean         cut_sub_process_get_multi_thread    (CutSubProcess *sub_process);
    void                cut_sub_process_set_multi_thread    (CutSubProcess *sub_process,
                                                             cut_boolean multi_thread);
    int                 cut_sub_process_get_max_threads     (CutSubProcess *sub_process);
    void                cut_sub_process_set_max_threads     (CutSubProcess *sub_process,
                                                             int max_threads);
    const char **       cut_sub_process_get_exclude_files   (CutSubProcess *sub_process);
    void                cut_sub_process_set_exclude_files   (CutSubProcess *sub_process,
                                                             const char **files);
    const char **       cut_sub_process_get_exclude_directories
                                                            (CutSubProcess *sub_process);
    void                cut_sub_process_set_exclude_directories
                                                            (CutSubProcess *sub_process,
                                                             const char **directories);
    const char **       cut_sub_process_get_target_test_case_names
                                                            (CutSubProcess *sub_process);
    void                cut_sub_process_set_target_test_case_names
                                                            (CutSubProcess *sub_process,
                                                             const char **names);
    const char **       cut_sub_process_get_target_test_names
                                                            (CutSubProcess *sub_process);
    void                cut_sub_process_set_target_test_names
                                                            (CutSubProcess *sub_process,
                                                             const char **names);
    double              cut_sub_process_get_elapsed         (CutSubProcess *sub_process);
    double              cut_sub_process_get_total_elapsed   (CutSubProcess *sub_process);
    cut_boolean         cut_sub_process_is_crashed          (CutSubProcess *sub_process);
    cut_boolean         cut_sub_process_get_fatal_failures  (CutSubProcess *sub_process);
    void                cut_sub_process_set_fatal_failures  (CutSubProcess *sub_process,
                                                             cut_boolean fatal_failures);
    CutSubProcessGroup * cut_take_new_sub_process_group     (void);
    void                cut_sub_process_group_add           (CutSubProcessGroup *group,
                                                             CutSubProcess *sub_process);
    cut_boolean         cut_sub_process_group_run           (CutSubProcessGroup *group);
    void                cut_sub_process_group_run_async     (CutSubProcessGroup *group);
    cut_boolean         cut_sub_process_group_wait          (CutSubProcessGroup *group);

## Description

If your test target supports multi-process and/or multi-thread, you need to test them. You can use CutSubProcess and CutSubProcessGroup to do it.

CutSubProcess runs your test on another process and forwards results of it to a test on your main process. You will get results of test on another process as results of test on your main process.

CutSubProcessGroup is a convenience object to run some CutSubProcess.

## Details

### CutSubProcess

    typedef struct _CutSubProcess CutSubProcess;

An object to represent sub cutter process. It contains sub cutter process's parameters and results of sub cutter process.

e.g.:

    1
    2
    3
    4
    5
    CutSubProcess *sub_process;

    sub_process = cut_take_new_sub_process("test-dir");
    cut_sub_process_set_multi_thread(sub_process, TRUE);
    cut_assert_true(cut_sub_process_run(sub_process));

Since 1.0.4

### CutSubProcessGroup

    typedef struct _CutSubProcessGroup CutSubProcessGroup;

An object to run sub cutter processes. This is just for convenience.

e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    CutSubProcess *sub_process1, *sub_process2, *sub_process3;
    CutSubProcessGroup *group;

    sub_process1 = cut_take_new_sub_process("test-dir1");
    sub_process2 = cut_take_new_sub_process("test-dir2");
    sub_process3 = cut_take_new_sub_process("test-dir3");

    group = cut_take_new_sub_process_group();
    cut_sub_process_group_add(group, sub_process1);
    cut_sub_process_group_add(group, sub_process2);
    cut_sub_process_group_add(group, sub_process3);
    cut_assert_true(cut_sub_process_group_run(group));

Since 1.0.4

### cut_take_new_sub_process ()

    CutSubProcess *     cut_take_new_sub_process            (const char *test_directory);

Creates sub cutter process that runs tests under `test_directory` and returns it. A created sub process is owned by Cutter.

`test_directory` : | a directory includes sub process test.
Returns : | a CutSubProcess.

Since 1.0.4

### cut_sub_process_run ()

    cut_boolean         cut_sub_process_run                 (CutSubProcess *sub_process);

Runs sub cutter process.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` is completed successfully, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_run_async ()

    void                cut_sub_process_run_async           (CutSubProcess *sub_process);

Runs sub cutter process asynchronously. The result of `sub_process` can be gotten by `cut_sub_process_wait()`.

`sub_process` : | a CutSubProcess.

Since 1.0.4

### cut_sub_process_wait ()

    cut_boolean         cut_sub_process_wait                (CutSubProcess *sub_process);

Waits for sub cutter process that is ran asynchronously to complete and returns the result.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` is completed successfully, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_is_success ()

    cut_boolean         cut_sub_process_is_success          (CutSubProcess *sub_process);

Returns whether `sub_process` is completed successfully or not.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` is completed successfully, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_is_running ()

    cut_boolean         cut_sub_process_is_running          (CutSubProcess *sub_process);

Returns whether `sub_process` is running or not.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` is running, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_get_test_directory ()

    const char *        cut_sub_process_get_test_directory  (CutSubProcess *sub_process);

Returns a test directory that has tests to be ran.

`sub_process` : | a CutSubProcess.
Returns : | a test directory.

Since 1.0.4

### cut_sub_process_set_test_directory ()

    void                cut_sub_process_set_test_directory  (CutSubProcess *sub_process,
                                                             const char *test_directory);

Sets `test_directory` as a test directory that has tests to be ran. This is same as TEST_DIRECTORY required command line argument.

`sub_process` : | a CutSubProcess.
`test_directory` : | a test directory.

Since 1.0.4

### cut_sub_process_get_source_directory ()

    const char *        cut_sub_process_get_source_directory
                                                            (CutSubProcess *sub_process);

Returns a source directory that has source files.

`sub_process` : | a CutSubProcess.
Returns : | a source directory.

Since 1.0.4

### cut_sub_process_set_source_directory ()

    void                cut_sub_process_set_source_directory
                                                            (CutSubProcess *sub_process,
                                                             const char *source_directory);

Sets `source_directory` as a source directory that has source files. This is same as --source-directory command line option.

`sub_process` : | a CutSubProcess.
`source_directory` : | a source directory.

Since 1.0.4

### cut_sub_process_get_multi_thread ()

    cut_boolean         cut_sub_process_get_multi_thread    (CutSubProcess *sub_process);

Returns whether `sub_process` is ran in multi-thread mode.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` is ran in multi-thread mode, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_set_multi_thread ()

    void                cut_sub_process_set_multi_thread    (CutSubProcess *sub_process,
                                                             cut_boolean multi_thread);

Sets whether `sub_process` is ran in multi-thread mode or not. This is same as --multi-thread command line option.

`sub_process` : | a CutSubProcess.
`multi_thread` : | `CUT_TRUE` to be ran in multi-thread mode.

Since 1.0.4

### cut_sub_process_get_max_threads ()

    int                 cut_sub_process_get_max_threads     (CutSubProcess *sub_process);

Returns how many threads are used concurrently at a maximum in `sub_process`.

`sub_process` : | a CutSubProcess.
Returns : | max number of threads used concurrently at a maximum in `sub_process`.

Since 1.0.5

### cut_sub_process_set_max_threads ()

    void                cut_sub_process_set_max_threads     (CutSubProcess *sub_process,
                                                             int max_threads);

Sets how many threads are used concurrently at a maximum in `sub_process`. -1 means no limit. This is same as --max-threads command line option.

`sub_process` : | a CutSubProcess.
`max_threads` : | max number of threads used concurrently at a maximum.

Since 1.0.5

### cut_sub_process_get_exclude_files ()

    const char **       cut_sub_process_get_exclude_files   (CutSubProcess *sub_process);

Returns file names that are excluded from target test files.

`sub_process` : | a CutSubProcess.
Returns : | file names that are excluded from target test files.

Since 1.0.4

### cut_sub_process_set_exclude_files ()

    void                cut_sub_process_set_exclude_files   (CutSubProcess *sub_process,
                                                             const char **files);

Sets file names that are excluded from target test files. This is same as --exclude-file command line option.

`sub_process` : | a CutSubProcess.
`files` : | file names that are excluded from target test files.

Since 1.0.4

### cut_sub_process_get_exclude_directories ()

    const char **       cut_sub_process_get_exclude_directories
                                                            (CutSubProcess *sub_process);

Returns directory names that are excluded from target test directories.

`sub_process` : | a CutSubProcess.
Returns : | directory names that are excluded from target test directories.

Since 1.0.4

### cut_sub_process_set_exclude_directories ()

    void                cut_sub_process_set_exclude_directories
                                                            (CutSubProcess *sub_process,
                                                             const char **directories);

Sets directory names that are excluded from target test directories. This is same as --exclude-directory command line option.

`sub_process` : | a CutSubProcess.
`directories` : | directory names that are excluded from target test directories.

Since 1.0.4

### cut_sub_process_get_target_test_case_names ()

    const char **       cut_sub_process_get_target_test_case_names
                                                            (CutSubProcess *sub_process);

Returns test case names that are ran.

`sub_process` : | a CutSubProcess.
Returns : | test case names that are ran.

Since 1.0.4

### cut_sub_process_set_target_test_case_names ()

    void                cut_sub_process_set_target_test_case_names
                                                            (CutSubProcess *sub_process,
                                                             const char **names);

Sets test case names that are ran. This is same as --test-case command line option.

`sub_process` : | a CutSubProcess.
`names` : | test case names that are ran.

Since 1.0.4

### cut_sub_process_get_target_test_names ()

    const char **       cut_sub_process_get_target_test_names
                                                            (CutSubProcess *sub_process);

Returns test names that are ran.

`sub_process` : | a CutSubProcess.
Returns : | test names that are ran.

Since 1.0.4

### cut_sub_process_set_target_test_names ()

    void                cut_sub_process_set_target_test_names
                                                            (CutSubProcess *sub_process,
                                                             const char **names);

Sets test names that are ran. This is same as --test command line option.

`sub_process` : | a CutSubProcess.
`names` : | test names that are ran.

Since 1.0.4

### cut_sub_process_get_elapsed ()

    double              cut_sub_process_get_elapsed         (CutSubProcess *sub_process);

Gets the time while `sub_process` was running.

`sub_process` : | a CutSubProcess.
Returns : | the time while `sub_process` was running.

Since 1.0.4

### cut_sub_process_get_total_elapsed ()

    double              cut_sub_process_get_total_elapsed   (CutSubProcess *sub_process);

Gets the sum of times that are used by each test.

`sub_process` : | a CutSubProcess.
Returns : | the sum of times that are used by each test.

Since 1.0.4

### cut_sub_process_is_crashed ()

    cut_boolean         cut_sub_process_is_crashed          (CutSubProcess *sub_process);

Returns whether `sub_process` was crashed or not.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` was crashed, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_get_fatal_failures ()

    cut_boolean         cut_sub_process_get_fatal_failures  (CutSubProcess *sub_process);

Returns whether `sub_process` is ran in fatal-failures mode. See `cut_sub_process_set_fatal_failures()` more details of fatal-failures mode.

`sub_process` : | a CutSubProcess.
Returns : | `CUT_TRUE` if `sub_process` is ran in fatal-failures mode, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_set_fatal_failures ()

    void                cut_sub_process_set_fatal_failures  (CutSubProcess *sub_process,
                                                             cut_boolean fatal_failures);

Sets whether `sub_process` is ran in fatal-failures mode or not. In this mode, all failures are treated as fatal problems. It means that test is aborted on failure. On some environments, breakpoint is set.

This is same as --fatal-failures command line option.

`sub_process` : | a CutSubProcess.
`fatal_failures` : | `CUT_TRUE` to be ran in fatal-failures mode.

Since 1.0.4

### cut_take_new_sub_process_group ()

    CutSubProcessGroup * cut_take_new_sub_process_group     (void);

Creates a group of sub cutter process. A created group is owned by Cutter.

Returns : | a CutSubProcessGroup.

Since 1.0.4

### cut_sub_process_group_add ()

    void                cut_sub_process_group_add           (CutSubProcessGroup *group,
                                                             CutSubProcess *sub_process);

Adds `sub_process` to `group`.

`group` : | a CutSubProcessGroup.
`sub_process` : | a CutSubProcess.

Since 1.0.4

### cut_sub_process_group_run ()

    cut_boolean         cut_sub_process_group_run           (CutSubProcessGroup *group);

Runs all sub cutter processes of `group` and returns the result of them.

`group` : | a CutSubProcessGroup.
Returns : | `CUT_TRUE` if all sub cutter processes of `group` are completed successfully, `CUT_FALSE` otherwise.

Since 1.0.4

### cut_sub_process_group_run_async ()

    void                cut_sub_process_group_run_async     (CutSubProcessGroup *group);

Runs all sub cutter processes of `group` asynchronously. The result of them can be gotten by `cut_sub_process_group_wait()`.

`group` : | a CutSubProcessGroup.

Since 1.0.4

### cut_sub_process_group_wait ()

    cut_boolean         cut_sub_process_group_wait          (CutSubProcessGroup *group);

Waits for all sub cutter processes of `group` that are ran asynchronously to complete and returns the result.

`group` : | a CutSubProcessGroup.
Returns : | `CUT_TRUE` if all sub cutter processes of `group` are completed successfully, `CUT_FALSE` otherwise.

Since 1.0.4