/*
 *
 *
 *    watchable.h
 *
 *    C++ header file for class 'watchable.'
 *
 *    =========================================================================
 *
 *    Copyright (C) 2001-2003 by Matt Roberts, KK5JY.
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation; either
 *    version 2.1 of the License, or (at your option) any later version.
 *
 *    This library 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
 *    Lesser General Public License for more details.
 *
 *    You should have received a copy of the GNU Lesser General Public
 *    License along with this library; if not, write to the Free Software
 *    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *    =========================================================================
 *
 *
 */


#ifndef __WATCHABLE_H
#define __WATCHABLE_H

	#include <stddef.h>

	namespace my {

		/*
		 *
		 *
		 *    class my::watchable
		 *
		 *    Defines an interface that all I/O classes should use to participate
		 *    in I/O multiplexing.
		 *
		 *    Derived classes MUST IMPLEMENT each {read|write|except}_desc() function
		 *    corresponding to each watch type (read, write, exception) for which the
		 *    derived type objects may wish to be watched for activity.
		 *
		 *    Derived classes MAY OPTIONALLY IMPLEMENT any of the {read|write|except}_action
		 *    functions, which will be called by the multiplex class when the derived type
		 *    object has an event of the respective type pending.  The return value of the
		 *    *_action() function will be used by the appropriate can_*() function of
		 *    my::multiplex.  When an event occurs, *_action() will be called.  That function
		 *    should return true, but can be overridden by a subclass, if that is not the desired
		 *    return value to offer to the client when calling my::multiplex::can_*().
		 *
		 *
		 */

		class multiplex;

		class watchable {
			protected: // file descriptor interface for derived classes
				friend class multiplex;

				virtual int read_desc (void) = 0;
				virtual int write_desc (void) = 0;
				virtual int except_desc (void) = 0;

			protected: // action interface for derived classes
				virtual bool read_action (void) { return true; };
				virtual bool write_action (void) { return true; };
				virtual bool except_action (void) { return true; };

			protected: // directives to tell the mux what to watch
				virtual bool should_watch_read (void) { return false; };
				virtual bool should_watch_write (void) { return false; };
				virtual bool should_watch_except (void) { return false; };

			public:
				virtual ~watchable (void) { /* noop */ };

			public: // public interface to query queue lengths
				virtual size_t tx_queue (void) const = 0;
				virtual size_t rx_queue (void) const = 0;
		};

	}

#endif /* __WATCHABLE_H */
