From 89c4f3f53fd5b9f99102ba7922328f06c74d6833 Mon Sep 17 00:00:00 2001 From: zenon Date: Sat, 9 Jun 2018 13:28:30 +0200 Subject: [PATCH] Add comments for functions and make functions static --- generator.c | 158 ++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 130 insertions(+), 28 deletions(-) diff --git a/generator.c b/generator.c index 916851e..1f8b6b9 100644 --- a/generator.c +++ b/generator.c @@ -8,44 +8,92 @@ #include "common.h" #include +/** + * @details Global variable for the program name. + */ static const char *pname; +/** + * @details Global struct for shared memory. + */ static struct circ_buf *shared; -int shmfd; +/** + * @details Global file descriptor for shared memory. + */ +static int shmfd; +/** + * @details Semaphore for tracking the used space in shared memory. + */ static sem_t *sUsedSpace; +/** + * @details Semaphore for tracking the free space in shared memory. + */ static sem_t *sFreeSpace; +/** + * @details Semaphore for exclusive access to shared memory for generators. + */ static sem_t *sWriteEnd; -struct sigaction sa; +/** + * @details Struct for signal handler. + */ +static struct sigaction sa; +/** + * @details struct which stores a node in an adjacency list. + */ struct AdjListNode { int dest; struct AdjListNode *next; }; +/** + * @details Struct which respresents an adjacency list. Stores a pointer to + * the first element. + */ struct AdjList { struct AdjListNode *head; }; +/** + * @details Struct which stores a graph made up of the count of nodes and an + * array for the adjacency lists. + */ struct Graph { int V; struct AdjList *array; }; -static struct Graph graph; +/** + * @details Global graph which gets populated by parse(). + */ +struct Graph graph; +/** + * @details Variable which gets set on signal received. + */ static volatile sig_atomic_t quit = 0; +/** + * @details Signal handler. + * @param signum The number of the received signal. + * @return This function has no return value. + */ static void sig_handler(int signum) { quit = 1; } -void usage(void) +/** + * @details Prints the synopsis. + * @param void This function takes no parameters. + * @return Always non-zero. + */ +static void usage(void) { fprintf(stderr, "SYNOPSIS\n" "\tgenerator EDGE1...\n" @@ -54,7 +102,12 @@ void usage(void) exit(EXIT_FAILURE); } -struct AdjListNode *newAdjListNode(int dest) +/** + * @details Function which creates a new adjacency list node. + * @param dest The value of the node. + * @return Returns the new node. + */ +static struct AdjListNode *newAdjListNode(int dest) { struct AdjListNode *newNode = malloc(sizeof(struct AdjListNode)); newNode->dest = dest; @@ -62,7 +115,12 @@ struct AdjListNode *newAdjListNode(int dest) return newNode; } -void createGraph(int V) +/** + * @details Function which creates a new graph. + * @param V The number of nodes in the new graph. + * @return This function has no return value. + */ +static void createGraph(int V) { graph.V = V; @@ -72,14 +130,26 @@ void createGraph(int V) graph.array[i].head = NULL; } -void addEdge(int src, int dest) +/** + * @details This function adds a new edge from src to dest. + * @param src The source node of the edge. + * @param dest The destination node of the edge. + * @return This function has no return value. + */ +static void addEdge(int src, int dest) { struct AdjListNode *newNode = newAdjListNode(dest); newNode->next = graph.array[src].head; graph.array[src].head = newNode; } -int strToInt(char *str) +/** + * @details Function which safely converts a string to an integer. + * @param str The string to be converted. + * @return -2 if out of range (long). -1 if out of range (int). Converted value + * on success. + */ +static int strToInt(char *str) { char *endptr; long val; @@ -99,7 +169,13 @@ int strToInt(char *str) return (int) val; } -void parse(int argc, char *argv[]) +/** + * @details Function which parses the commandline arguments and populates the graph. + * @param argc The number of supplied commandline arguments. + * @param argv The array of supplied commandline arguments. + * @return This function has no return value. + */ +static void parse(int argc, char *argv[]) { char *token; int V = 0; @@ -165,20 +241,13 @@ void parse(int argc, char *argv[]) } } -void printGraph() -{ - for (int v = 0; v < graph.V; v++) { - struct AdjListNode* pCrawl = graph.array[v].head; - printf("\n Adjacency list of vertex %d\n head ", v); - while (pCrawl) { - printf("-> %d", pCrawl->dest); - pCrawl = pCrawl->next; - } - printf("\n"); - } -} - -void cleanup() +/** + * @details Cleanup function which frees memory and closes shared memory and + * semaphores. + * @param void This function takes no parameters. + * @return 0 on success, non-zero on failure. + */ +static void cleanup(void) { sem_post(sWriteEnd); sem_post(sFreeSpace); @@ -207,8 +276,12 @@ void cleanup() exit(EXIT_SUCCESS); } - -void wait_sem(sem_t *sem) +/** + * @details Custom sem_wait function which listens for signals. + * @param sem Semaphore to be decremented. + * @return This function has no return value. + */ +static void wait_sem(sem_t *sem) { while (sem_wait(sem) == -1) { // interrupted by syscall? if (errno == EINTR) { @@ -224,7 +297,12 @@ void wait_sem(sem_t *sem) return; } -void putSolution(int *solution) +/** + * @details Function which writes a solution to the shared memory buffer. + * @param solution The solution to be written to shared memory. + * @return This function has no return value. + */ +static void putSolution(int *solution) { wait_sem(sWriteEnd); @@ -248,7 +326,14 @@ void putSolution(int *solution) sem_post(sWriteEnd); } -int findIndex(int array[], int value, int size) +/** + * @details Function which finds the index of a specific value in an array. + * @param array The array in which the desired value resides. + * @param value The value to search for. + * @param size The size of the array. + * @return -1 if value not found in array. The index of value if found. + */ +static int findIndex(int array[], int value, int size) { int index = 0; while (index < size && array[index] != value) @@ -257,7 +342,15 @@ int findIndex(int array[], int value, int size) return (index == size ? -1 : index); } -void genSolution(int permutation[], int V, int *solution) +/** + * @details Function which receives a random permutation of the nodes and finds + * a random set of edges which - if removed - leave an acyclic graph. + * @param permutation The random permutation of the nodes. + * @param V The number of nodes in the graph. + * @param solution Contains the solution of edges at the end. + * @return This function has no return value. + */ +static void genSolution(int permutation[], int V, int *solution) { if (shared->quit == 1) { quit = 1; @@ -302,6 +395,15 @@ void genSolution(int permutation[], int V, int *solution) } } +/** + * The main entry point of the program. + * @details Sets up signal handler, shared memory and semaphores, parses the + * commandline arguments and periodically generates a new solution and + * submits it to the shared memory. + * @param argc The number of commandline arguments. + * @param argv The array of commandline arguments. + * @return 0 on success, non-zero on failure. + */ int main(int argc, char *argv[]) { if (argc == 1)