From 95491e280363ddaed05599445138fd8191110dc1 Mon Sep 17 00:00:00 2001 From: Andre Date: Tue, 13 Jun 2006 03:53:48 +0200 Subject: [PATCH] complete documentation of stdin.* and stdout.* --- stdin.c | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++---- stdin.h | 6 ++++-- stdout.c | 19 ++++++++--------- stdout.h | 31 +++++++++++++++++++++++++++- 4 files changed, 101 insertions(+), 17 deletions(-) diff --git a/stdin.c b/stdin.c index d33be358..b86fbbb9 100644 --- a/stdin.c +++ b/stdin.c @@ -1,3 +1,23 @@ +/* + * Copyright (C) 2006 Andre Noll + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA. + */ + +/** \file stdin.c functions that deal with reading from stdin */ + #include "para.h" #include "string.h" #include "list.h" @@ -6,12 +26,25 @@ #include "error.h" #include "stdin.h" +/** + * the pre_select function of the stdin task + * + * \param s the scheduler this task was registered to + * \param t the task structure of the stdin task + * + * This function is always successful. If there is space left in the + * buffer of the stdin task, it adds \a STDIN_FILENO to the read fd set + * of \a s. + */ void stdin_pre_select(struct sched *s, struct task *t) { struct stdin_task *sit = t->private_data; - if (sit->loaded < sit->bufsize) - para_fd_set(STDIN_FILENO, &s->rfds, &s->max_fileno); - t->ret = 1; /* success */ + t->ret = 1; + sit->check_fd = 0; + if (sit->loaded >= sit->bufsize) + return; + sit->check_fd = 1; + para_fd_set(STDIN_FILENO, &s->rfds, &s->max_fileno); } static void stdin_default_event_handler(struct task *t) @@ -20,13 +53,24 @@ static void stdin_default_event_handler(struct task *t) unregister_task(t); } +/** + * the post select function of the stdin task + * + * \param s the scheduler this task was registered to + * \param t the task structure of the stdin task + * + * This function checks if \a STDIN_FILENO was included by in the read fd set + * of \a s during the previous pre_select call. If yes, and STDIN_FILENO + * appeears to be readable, data is read from stdin into the buffer of the + * stdin task. + */ void stdin_post_select(struct sched *s, struct task *t) { struct stdin_task *sit = t->private_data; ssize_t ret; t->ret = 1; - if (sit->loaded >= sit->bufsize) + if (!sit->check_fd) return; if (!FD_ISSET(STDIN_FILENO, &s->rfds)) return; @@ -42,6 +86,16 @@ void stdin_post_select(struct sched *s, struct task *t) sit->eof = 1; } +/** + * initialize a stdin task structure with default values + * + * \param sit the stdin task structure + * + * This fills in the pre/post select function poinzters of the task structure + * given by \a sot. It also sets up a default error handler which unregisters + * the task. Moreover, \a loaded and \a eof are set to zero and \a bufsize is + * initialized to 16 KB (but no buffer is allocated). + */ void stdin_set_defaults(struct stdin_task *sit) { sit->bufsize = 16 * 1024, diff --git a/stdin.h b/stdin.h index b9ee68be..a36b9887 100644 --- a/stdin.h +++ b/stdin.h @@ -19,7 +19,7 @@ /** \file stdin.h the stdin task structure and exported symbols from stdin.c */ /** - * the task structure used when reading from stdin + * the task structure used for reading from stdin */ struct stdin_task { /** input buffer */ @@ -28,9 +28,11 @@ struct stdin_task { size_t bufsize; /** number of bytes currently loaded in \a buf */ size_t loaded; + /** whether STDIN_FILENO was included in the read fd set */ + int check_fd; /** the task structure */ struct task task; - /** non-zero if a read from stdin returned zero */ + /** non-zero on read error, or if a read from stdin returned zero */ int eof; }; diff --git a/stdout.c b/stdout.c index e13d0f18..25402b8d 100644 --- a/stdout.c +++ b/stdout.c @@ -33,9 +33,8 @@ * \param s the scheduler this task was registered to * \param t the task structure of the stdout task * - * This function is always successful. If there is data - * available in the input buffer, it adds the STDOUT_FILENO - * to the write fd set of \a s. + * This function is always successful. If there is data available in the input + * buffer, it adds \a STDOUT_FILENO to the write fd set of \a s. */ void stdout_pre_select(struct sched *s, struct task *t) { @@ -61,9 +60,10 @@ void stdout_pre_select(struct sched *s, struct task *t) * \param s the scheduler this task was registered to * \param t the task structure of the stdout task * - * This function checks if STDOUT_FILENO was included by in the write fd set of - * \a s during the previous pre_select call. If yes, and STDOUT_FILENO appeears - * to be writable, the data loaded in the input buffer is written to stdout. + * This function checks if \a STDOUT_FILENO was included by in the write fd set + * of \a s during the previous pre_select call. If yes, and STDOUT_FILENO + * appeears to be writable, the data loaded in the input buffer is written to + * stdout. */ void stdout_post_select(struct sched *s, struct task *t) { @@ -97,10 +97,9 @@ static void stdout_default_event_handler(struct task *t) * * \param sot the stdout task structure * - * This fills in the pre/post select function poinzters of the task - * structure given by \a sot. It also sets up a default error handler - * which unregisteres the task on errors and clears the eof flag of - * \a sot. + * This fills in the pre/post select function poinzters of the task structure + * given by \a sot. It also sets up a default error handler which unregisters + * the task on errors and clears the eof flag of \a sot. */ void stdout_set_defaults(struct stdout_task *sot) { diff --git a/stdout.h b/stdout.h index 4dafafde..1fe09f1d 100644 --- a/stdout.h +++ b/stdout.h @@ -1,11 +1,40 @@ -/** \file stdout.h common code for uitlities that write to stdout */ +/* + * Copyright (C) 2006 Andre Noll + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA. + */ + +/** \file stdout.h the stdout task structure and exported symbols from stdout.c */ + +/** + * the task structure used for writing to stdout + */ struct stdout_task { + /** pointer to the data buffer */ char *buf; + /** the size of \a buf */ size_t *bufsize; + /** number of bytes loaded in \a buf */ size_t *loaded; + /** pointer to the eof flag of the feeding task */ int *input_eof; + /** non-zero if a write error occured */ int eof; + /** the task structure */ struct task task; + /** whether STDOUT_FILENO was included in the write fd set */ int check_fd; }; -- 2.39.2