style for files taglialegna.* apiFile.*

lib/threadpool/apiFile.h

@@ -4,64 +4,159 @@
 
 #include <pthread.h>
 
-#include <fileQueue.h>
-#include <taglialegna.h>
-/* TODO: finire tutte le descrizioni */
+#include "fileQueue.h"
+#include "taglialegna.h"
 
 #define C_CREATE 1
 #define C_LOCK 2
 
-
-// Lista dei client in attesa su una lock
+/* structure for the list of clients waiting for a lock */
 typedef struct struct_waiting {
-    long fd;                     // client in attesa
-    char *file;                  // file su cui si vuole acquisire la lock
-    struct struct_waiting *next; // puntatore al prossimo elemento della lista
+    long fd;                     /* client waiting */
+    char *file;                  /* file waiting the lock on */
+    struct struct_waiting *next;
 } waiting_t;
 
 
 /**
- * Apri o crea un nuovo file
- * \param filepath: nome del file
- * \param flags:
- * \param q: queue in cui inserire il file
- * \param fd_c: owner
- * \param taglia_t:
+ * @brief Open or create new file
+ *
+ * @param filepath name of the file
+ * @param flags
+ * @param q queue to insert the file into
+ * @param fd_c owner
+ * @param taglia
  */
 void openFile(char *filepath, int flags, queueT *q, long fd_c, taglia_t *taglia);
 
-// Leggi un file e invialo al client
+
+/**
+ * @brief Read a file and send it to a client
+ *
+ * @param filepath name of the file
+ * @param q queue where the file is
+ * @param fd_c client
+ * @param taglia
+ */
 void readFile(char *filepath, queueT *q, long fd_c, taglia_t *taglia);
 
-// Invia al client $n file qualsiasi dalla queue
+
+/**
+ * @brief Send to the client n files from the queue
+ *
+ * @param num number of files to send
+ * @param q
+ * @param fd_c client
+ * @param taglia
+ */
 void readNFiles(int num, queueT *q, long fd_c, taglia_t *taglia);
 
-// Scrivi dati su un file già creato (append o overwrite)
+
+/**
+ * @brief Write to a file
+ *
+ * @param filepath
+ * @param size
+ * @param q
+ * @param fd_c client
+ * @param taglia
+ * @param append true if append, false if overwrite
+ */
 void writeFile(char *filepath, size_t size, queueT *q, long fd_c, taglia_t *taglia, int append);
 
-// Acquisisci lock di un file
+
+/**
+ * @brief Get the lock of a file
+ *
+ * @param filepath
+ * @param q
+ * @param fd_c client
+ * @param taglia
+ * @param lock lock of the waiting_t list
+ * @param waiting
+ */
 void lockFile(char *filepath, queueT *q, long fd_c, taglia_t *taglia, pthread_mutex_t *lock, waiting_t **waiting);
 
-// Rilascia una Lock di un file
+
+/**
+ * @brief Relese a lock
+ *
+ * @param filepath
+ * @param q
+ * @param fd_c client
+ * @param taglia
+ * @param lock lock of the waiting_t list
+ * @param waiting
+ */
 void unlockFile(char *filepath, queueT *q, long fd_c, taglia_t *taglia, pthread_mutex_t *lock, waiting_t **waiting);
 
-// Chiudi un file
+
+/**
+ * @brief Close a file and relese locks
+ *
+ * @param filepath
+ * @param q
+ * @param fd_c client
+ * @param taglia
+ * @param lock lock of the waiting_t list
+ * @param waiting
+ */
 void closeFile(char *filepath, queueT *q, long fd_c, taglia_t *taglia, pthread_mutex_t *lock, waiting_t **waiting);
 
-// Rimuovi un file
+
+/**
+ * @brief Delete a file
+ *
+ * @param filepath
+ * @param q
+ * @param fd_c client
+ * @param taglia
+ * @param lock lock of the waiting_t list
+ * @param waiting
+ */
 void removeFile(char *filepath, queueT *q, long fd_c, taglia_t *taglia, pthread_mutex_t *lock, waiting_t **waiting);
 
 
-// Funzione ausiliaria che invia un file al client
+/**
+ * @brief Send a file to the client
+ *
+ * @param f file to send
+ * @param fd_c client
+ * @param taglia
+ * @return 0 if success, -1 if error
+ */
 int sendFile(fileT *f, long fd_c, taglia_t *taglia);
 
-// Aggiunge una coppia client/file alla coda in attesa di ottenere una lock
+/**
+ * @brief Add the client to the waiting list for the lock on the file
+ *
+ * @pre the lock of the waiting list must be acquired
+ *
+ * @param waiting
+ * @param filepath
+ * @param fd_c client
+ * @return 0 if success, -1 if error
+ */
 int addWaiting(waiting_t **waiting, char *filepath, int fd_c);
 
-// Ottiene il primo client in attesa su una lock di un determinato file
+
+/**
+ * @brief Delete a file
+ *
+ * @pre the lock of the waiting list must be acquired
+ *
+ * @param waiting
+ * @param filepath
+ * @return the file descriptor of the client or -1 if no found
+ */
 int removeFirstWaiting(waiting_t **waiting, char *filepath);
 
-// Distrugge la lista d'attesa e ne libera la memoria
+
+/**
+ * @brief Frees the waiting_t structure
+ *
+ * @param waiting
+ */
 void clearWaiting(waiting_t **waiting);
 
 #endif // _API_FILE