Skip to content
Extraits de code Groupes Projets
Valider 77f71400 rédigé par Aurélien Buxant's avatar Aurélien Buxant
Parcourir les fichiers

README.txt --> README.md

parent bcc028b3
Aucune branche associée trouvée
Aucune étiquette associée trouvée
Aucune requête de fusion associée trouvée
Pipeline #8075 en échec
# Projet 3 # README Group Q6
# Authors : Giovanna Stefanelli, Lucas Bosmans, Aurélien Buxant and Yohan Burignat
Welcome to project 3! Program: "fact"
## TABLE OF CONTENTS
* [0. General Info]
* [1. Installation Steps]
* [2. Programme General Architecture]
* [3. Main Data Structures]
* [4. Function Description]
Dans ce dossier se trouvent les fichiers initiaux pour le projet du cours LEPL1503.
- `example_input.txt` : Exemple de fichier d'entrée du projet.
- `example_output.txt` : Exemple de fichier de sortie correspondant au fichier exemple d'entrée.
- `prime_divs.py` : Programme python non optimisé.
Place pour chaque nombre dans le fichier d'entrée une ligne dans le fichier de sortie
"nombre div1 div2 ..." avec à la suite du nombre la liste de ses diviseurs premiers.
Le 1er argument du programme est le nom du fichier d'entrée,
et le deuxième est le nom du fichier de sortie
(il sera créé s'il n'existe pas, sinon son contenu sera remplacé).
- `test_prime_divs.py` : Programme de tests du programme `prime_divs.py`.
- `README.md` : Ce fichier.
## 0. General Info
`Aim of the program`:
This program 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. 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: can be called with this sintax:
./fact [-N number_of_threads] input_file.txt output_file.txt ./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. Whether the number of threads is not defined, the default number of threads is 2.
The program performance could not increase with a too high number of threads The programme 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). because, above all, it will depend on the machine architecture (e.g. number of cores).
The maximum number of threads allowed by the program is 20, nevertheless The maximum number of threads allowed by the programme is 20, nevertheless
the program "fact" can be updated by changing the constant MAX_NO_THREADS the programme "fact" can be updated by changing the constant MAX_NO_THREADS
(#define MAX_NO_THREADS 20). (#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"
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")
- "make test" compiles "Fact_UnitTest.c", the unit tests are performed
with the command "make cunit", (Note: in Windows we have "Fact_UnitTest.exe").
- "make clean" deletes the executable "fact", all the output files
with the prefix "out" (e.g. output.txt, out_result.txt, out.txt, ...)
and the files produced by unit tests.
To these basic operations more tags are provided, in particular:
- "make cunit" prepares the environment and execute the Cunit test
on the main "fact" functions. The result is redirected into the file
"Cunit_test_file.txt"
- "make valgrind" executes the tool valgrind on "fact" and the results
are redirected into the file "valgrind_fact.txt"
- "make cppcheck" executes the tool cppcheck on "fact" and the results
are redirected into the file "cppcheck_fact.txt".
- "make valgrind_cunit" executes the tool valgrind on "Fact_UnitTest"
and the results are redirected into the file "valgrind_cunit.txt".
- "make cppcheck_cunit" executes the tool cppcheck on "Fact_UnitTest"
and the results are redirected into the file "cppcheck_cunit.txt".
c. The input file "example_input.txt" contains the numbers to be factorized (one
per line). This file allows to verify the correct calculation by comparing the
ouput with the results stored into another file: "example_output.txt".
Note: "example_input.txt" and "example_output.txt" are the files provided by
the project specification (at the initial project stage). These files
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.
e. The file "Fact_UnitTest.c" contains the unit tests code exploiting the facility
of the "CUnit" library.
f. The files "valgrind_fact.txt", "cppcheck_fact.txt" and "Cunit_test_file.txt"
are the output of valgrind, cppcheck tools and CUnit tests.
## 2. Programme General Architecture
The programme 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
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
by the various active threads.
A general overview of "fact" architecture is depichted herebelow:
main(argc,argv[]) is_prime
\/ /
Thread[1]--> read_write|--> prime_divs
| \
| is_div is_prime
| /
Thread[2]--------> read_write|--------> prime_divs
| \
| is_div is_prime
| /
Thread[3]--------------> read_write|--------------> prime_divs
: \
: is_div
: is_prime
: /
Thread[n]--------------------> read_write|--------------------> prime_divs
\
is_div
Note: This architecture can be easily adapted to parallel machine.
## 3. Main Data Structures
Two major global data structure are used by the programme:
- 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:
typedef struct factorization {
unsigned long prime_dividers[N];
unsigned int cnt;
unsigned long number;
} factor;
- the second data structure stores the file descriptors of the
input and output files.
The structure is:
typedef struct file_descriptors {
FILE *in;
FILE *out;
} fd;
The programme 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
such as "unsigned long long" or "int64_t". The use of "int64_t" type
needs to include in the "fact" programme: "#include <stdint.h>".
## 4. Function Description
As drawn in the scheme of the "Programme General Architecture" the programme
"fact" is composed by 4 functions:
-> void *read_write()
This function is activated by each threads created in the "main".
It is responsible for reading each number from the input file,
line by line, and for the writing of the number alone if prime,
otherwise the prime dividers are recorded after the number.
-> factor *prime_divs(unsigned long numbr)
This function is charged to calculate the prime dividers by calling
first "is_div" and in case a factor of the number is found,
"is_prime" is executed.
The calling sequence of "is_div" and "is_prime" it is important
because the function "is_prime" is more cpu time demanding.
-> bool is_prime(unsigned long nbr)
This function determines if a number is prime. To speed up the
computation, the algorithm is based on the "Sieve of Eratosthenes"
(see "https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes")
-> bool is_div(unsigned long numbr, unsigned long i)
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
(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 "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,
- the mutex is initialised,
- the threads are created calling the function "read_write",
- the threads are joined,
- the cpu time is stopped and calculated,
- the mutex is destroyed,
- the input and output files are closed
- the main return zero.
0% Chargement en cours ou .
You are about to add 0 people to the discussion. Proceed with caution.
Terminez d'abord l'édition de ce message.
Veuillez vous inscrire ou vous pour commenter