diff --git a/README.txt b/README.txt index b3dafc4fff3764ba5fe65d3e857b89a4c0441c40..69eeb4405ce15661075149c169e79987e8cae634 100644 --- a/README.txt +++ b/README.txt @@ -1,35 +1,35 @@ README -Programme: "fact" +Program: "fact" ## TABLE OF CONTENTS * [0. General Info] * [1. Installation Steps] -* [2. Programme General Architecture] +* [2. Program General Architecture] * [3. Main Data Structures] * [4. Function Description] ## 0. General Info -This programme allows to determine if a number is prime otherwise its prime +This program allows to determine if a number is prime otherwise its prime dividers are calculated. -The numbers to be considered shall be in an file (*.txt) then the programme +The numbers to be considered shall be in an file (*.txt) then the program can be called with this sintax: ./fact [-N number_of_threads] input_file.txt output_file.txt Whether the number of threads is not defined, the default number of threads is 2. -The programme performance could not increase with a too high number of threads +The program performance could not increase with a too high number of threads because, above all, it will depend on the machine architecture (e.g. number of cores). -The maximum number of threads allowed by the programme is 20, nevertheless -the programme "fact" can be updated by changing the constant MAX_NO_THREADS +The maximum number of threads allowed by the program is 20, nevertheless +the program "fact" can be updated by changing the constant MAX_NO_THREADS (#define MAX_NO_THREADS 20). ## 1. Installation Steps -The programme directory includes several files, a list is provided herebelow: -a. The C programme file "fact.c" +The program directory includes several files, a list is provided herebelow: +a. The C program file "fact.c" b. The "Makefile" with three basic "make" operations: - "make fact" compiles "fact.c" and create the executable "fact" (Note: in Windows we have "fact.exe") @@ -59,7 +59,7 @@ c. The input file "example_input.txt" contains the numbers to be factorized (one are not deleted by "make clean". d. The input file "incorrect_numbers.txt" contains numbers out of the scope of the - programme fact (e.g. numbers < 2). This file can be used for testing purposes. + program fact (e.g. numbers < 2). This file can be used for testing purposes. e. The file "Fact_UnitTest.c" contains the unit tests code exploiting the facility of the "CUnit" library. @@ -69,10 +69,10 @@ are the output of valgrind, cppcheck tools and CUnit tests. -## 2. Programme General Architecture -The programme architecture exploits threads to perform parallel factoring operations. +## 2. Program General Architecture +The program architecture exploits threads to perform parallel factoring operations. The architecture tries to reduce to the minimum the number of zones protected by -mutex to increase the general "fact" performances. Only one area in the programme +mutex to increase the general "fact" performances. Only one area in the program is protected by the concurrency (i.e. only one thread at a time is allowed). In particular the set of instructions under mutex control are dedicated to write the results in the output file, this is to avoid the overwriting of the final results @@ -102,11 +102,11 @@ Note: This architecture can be easily adapted to parallel machine. ## 3. Main Data Structures -Two major global data structure are used by the programme: +Two major global data structure are used by the program: - the first stores: the number to factorised, the prime dividers and number of dividers. The prime dividers are saved in an array. This buffer - has a lenght of 8 places but can be increased changing the constant - "N" in "#define N 8". The structure is: + has a lenght of 10 places but can be increased changing the constant + "N" in "#define N 10". The structure is: typedef struct factorization { unsigned long prime_dividers[N]; @@ -123,16 +123,16 @@ typedef struct file_descriptors { FILE *out; } fd; -The programme takes care of big number for a maximum of 64 bits. This is +The program takes care of big number for a maximum of 64 bits. This is implemented through the "unsigned long" type, nevertheless according -the target machine, the programme can be modified with different types +the target machine, the program can be modified with different types such as "unsigned long long" or "int64_t". The use of "int64_t" type -needs to include in the "fact" programme: "#include <stdint.h>". +needs to include in the "fact" program: "#include <stdint.h>". ## 4. Function Description -As drawn in the scheme of the "Programme General Architecture" the programme +As drawn in the scheme of the "Program General Architecture" the program "fact" is composed by 4 functions: -> void *read_write() This function is activated by each threads created in the "main". @@ -153,10 +153,9 @@ As drawn in the scheme of the "Programme General Architecture" the programme This function exploits the operator "%" (modulo) to determine if a number has a divider. -Finally, the "main" is charged to check the programme arguments correctness +Finally, the "main" is charged to check the program arguments correctness (argc and argv[]) and, in case of error, a message is provided to -the user. The "fact" programme cannot calculate numbers < 2, a warning is -provided. +the user. The "fact" program can also calculate numbers < 2. The "main" performs the following sequential actions: - the start of cpu time, - the input and output files are opened, in case of error this is reported,