/* * The Unix Channel * * by Michel Beaudouin-Lafon * * Copyright 1990-1995 * Laboratoire de Recherche en Informatique (LRI) * * File descriptors, channels * * $Id$ * $CurLog$ */ #ifdef __GNUG__ #pragma implementation "Channel.h" #endif #include "Channel.h" #include "MsgBuffer.h" #include "error.h" #include "ccu/String.h" #include #include #include #include CH_HANDLER UchChannel::ReadHandler = 0; CH_HANDLER UchChannel::WriteHandler = 0; // // this section implements refcounts for file descriptors, so that they // are closed only when the last occurence is deleted // static int Refs [NFILE]; static int Inited = 0; /*?nodoc?*/ void UchFilDes :: Use (int fd) { if (fd < 0) return; if (! Inited) { Inited = 1; for (int i = 0; i < NFILE; i++) Refs [i] = 0; Refs [0] = Refs [1] = Refs [2] = 1; } Refs [fd]++; } /*?nodoc?*/ void UchFilDes :: Unuse (int fd) { if (fd < 0) return; if (--Refs [fd] == 0) close (fd); } /*?nodoc?*/ char* UchFilDes :: StrRepr (char* buf) { sprintf (buf, "%d", Fd); return buf; } /*?class UchFilDes This class implements objects representing Unix file descriptors. When the associated file descriptor is -1, the \typ{UchFilDes} is said to be closed, else it is said to be opened. Because several objects of this class can refer to the same file descriptor, the destructor closes the file descriptor only if it is the last object referring to this file descriptor. This is implemented with the help of a reference count, the overloading of \fun{operator =} and the definition of the constructor \fun{UchFilDes(const UchFilDes\&)}. All member functions described here are inline for maximum efficiency. ?*/ #ifdef DOC /*? Construct a closed file descriptor. ?*/ UchFilDes :: UchFilDes () { } /*? Construct an open file descriptor for the Unix file descriptor \var{fd}. In particular, this makes it possible to pass an integer where a \typ{UchFilDes} is normally expected. This is most useful when using Unix file descriptors. ?*/ UchFilDes :: UchFilDes (int fd) { } /*? This conversion operator makes it possible to pass a \typ{UchFilDes} argument where an integer is expected. This is most useful for system calls. ?*/ int UchFilDes :: operator int () { } /*? Return the Unix file descriptor, or -1 if it is closed. ?*/ int UchFilDes :: FilDes () { } /*? Open the object on file descriptor \var{fd}. If it was already opened, it is closed first. ?*/ void UchFilDes :: Open (int fd) { } /*? Close a file descriptor. If it is opened, this actually closes the file descriptor only if it was the last reference to it. \fun{Close} is automatically called by the destructor. ?*/ void UchFilDes :: Close () { } /*? Return true if the object is opened, false else. ?*/ bool UchFilDes :: Opened () { } /*? Read at most \var{n} bytes into buffer \var{b} and return the number of bytes actually read. This is the Unix \fun{read} system call. For efficiency, this function does not test whether the file descriptor is opened. ?*/ int UchFilDes :: Read (byte* b, int n) { } /*? Write at most \var{n} bytes of buffer \var{b} and return the number of bytes actually written. This is the Unix \fun{write} system call. For efficiency, this function does not test whether the file descriptor is opened. ?*/ int UchFilDes :: Write (byte* b, int n) { } #endif /* DOC */ /*?class UchChannel A \typ{UchChannel} is basically a file descriptor, with more strict semantics than a \typ{UchFilDes}. A channel is immutable: once initialized, it cannot change its file descriptor. It has a mode, of type \typ{^{IOMODE}}, with possible values \var{IONone}, \var{IORead}, \var{IOWrite}, \var{IOReadWrite}, \var{IOSelect}, \var{IOReadSelect}, \var{IOWriteSelect}, \var{IOAll}. \index{IOMODE :: IONone}\index{IOMODE :: IORead}\index{IOMODE :: IOWrite}\index{IOMODE :: IOReadWrite}\index{IOMODE :: IOSelect}\index{IOMODE :: IOReadSelect}\index{IOMODE :: IOWriteSelect}\index{IOMODE :: IOAll} Before being initialized, a UchChannel.has mode \var{IONone} and is said to be closed. A UchChannel.has a number of virtual functions. The destructor is virtual; this is useful for classes that store pointers to objects of a class derived from \typ{UchChannel} (like in the class \typ{UchSocket}). The functions \fun{HandleSelect}, \fun{HandleRead} and \fun{HandleWrite} are intended to give a channel the ability to automatically handle input/output, for instance for use with the \fun{select} system call. Such capabilities are used and thus illustrated in class \typ{UchMultiplexer}. The class \typ{^{pUchChannel}} implements smart pointers to channels. Smart pointers behave like pointers but they manage a reference count on the pointed to objects for an automatic reclaim of dynamically allocated objects. This is very useful especially in the class \typ{UchMultiplexer} because arrays of (smart) pointers to buffers are used. ?*/ /*? Construct a closed channel. ?*/ UchChannel :: UchChannel () : UchIOS (), Fd (), Mode (IONone), Mpx (0) { } /*? Construct an open channel on file descriptor \var{fd} with mode \var{io}. ?*/ UchChannel :: UchChannel (int fd, IOMODE io) : UchIOS (), Fd (fd), Mode (io), Mpx (0) { } /*?nodoc?*/ UchChannel :: UchChannel (const UchChannel& ch) : UchIOS (ch), Fd (ch.Fd), Mode (ch.Mode), Mpx (ch.Mpx) { } #ifdef DOC /*? Open the channel on file descriptor \var{fd}. A channel can only be opened once, and it cannot be closed. This function is useful when the channel was created with the default contructor, in order to associate a file descriptor to it. Because a channel is immutable, this can be done only once. ?*/ void UchChannel :: Open (int fd) { } /*?nextdoc?*/ IOMODE UchChannel :: IOMode () { } /*? Return/set the mode of the channel. ?*/ void UchChannel :: SetMode (IOMODE io) { } #endif /* DOC */ /*?nodoc?*/ UchChannel :: ~UchChannel () { // nothing special here } /*?nodoc?*/ UchChannel* UchChannel :: Copy () const { return new UchChannel (*this); } /*?nextdoc?*/ void UchChannel :: Added (UchBaseMultiplexer& m) { Mpx = &m; } /*? These virtual functions are called whenever a channel is added to (resp. removed from) a multiplexer. The default implementation only stores a pointer to the multiplexer (which can be retrieved through \fun{Getmultiplexer}). ?*/ void UchChannel :: Removed (UchBaseMultiplexer& m) { if (Mpx == &m) Mpx = 0; } /*?nextdoc?*/ void UchChannel :: HandleWrite () { if (! UchChannel::WriteHandler) ::Error (ErrFatal, "UchChannel::HandleWrite", ErrorTable [ErrShouldImplement]); else (* UchChannel::WriteHandler) (this); } /*? These virtual functions are called by a \typ{UchMultiplexer} when data can be written to the channel or read from the channel. They are are normally redefined in derived classes. The default implementation is the following: if the static members \var{UchChannel::ReadHandler} (resp. \var{UchChannel::WriteHandler}) is set, it is called by \fun{HandleRead} (resp. \fun{HandleWrite}); else an error message is output. These members are public so that they can be assigned directly at any time. By default they are not set. The type of these static members is \typ{^{CH\_HANDLER}}: pointer to void function with one argument of type \typ{UchChannel*}. ?*/ void UchChannel :: HandleRead () { if (! UchChannel::ReadHandler) ::Error (ErrFatal, "UchChannel::HandleRead", ErrorTable [ErrShouldImplement]); else (* UchChannel::ReadHandler) (this); } /*? This virtual function is called by a \typ{UchMultiplexer} before making a \fun{select} call. It is intended to handle any background task or buffered input/output associated to the channel. If it returns true, the channel set scan functions will return before performing the select call. See the class \typ{UchMultiplexer} for more details. The default implementation does nothing but returning false. ?*/ bool UchChannel :: HandleSelect () { return false; } #ifdef DOC /*?nextdoc?*/ int UchChannel :: Read (byte* b, int n) { } /*? The Unix \fun{read} and \fun{write} system calls, as in class \typ{UchFilDes}. ?*/ int UchChannel :: Write (byte* b, int n) { } #endif /* DOC */ /*?nextdoc?*/ int UchChannel :: Read (UchMsgBuffer& b) { int l = b.FreeLength (); if (! l) return -2; int n = read (Fd, (char*) b.Free (), l); if (n > 0) b.More (n); return n; } /*? The Unix \fun{read} and \fun{write} system calls applied to a \typ{UchMsgBuffer}. They return the number of bytes transferred, -1 if a system error occurred, -2 if the buffer is empty when writing or full when reading. ?*/ int UchChannel :: Write (UchMsgBuffer& b) { int l = b.BufLength (); if (! l) return -2; int n = write (Fd, (const char*) b.Buffer (), l); if (n > 0) b.Flush (n); return n; } /*?nextdoc?*/ bool UchChannel :: ReadBuffer (UchMsgBuffer& b) { int n; errno = 0; while ((n = Read (b)) > 0) ; return bool (n == -2); } /*? These functions repeatedly call \fun{Read} or \fun{Write} until the whole buffer is transferred or a system error occurred. In case of an error, they return false, else true. ?*/ bool UchChannel :: WriteBuffer (UchMsgBuffer& b) { int n; errno = 0; while ((n = Write (b)) > 0) ; return bool (n == -2); } void UchChannel :: WriteLong (lword l) { Write ((byte*)&l, lwsize); } void UchChannel :: WriteShort (sword s) { Write ((byte*)&s, swsize); } void UchChannel :: WriteByte (byte b) { Write (&b, 1); } void UchChannel :: WriteChar (char c) { Write ((byte*)&c, 1); } void UchChannel :: WriteString (const char* s) { Write ((byte*) s, strlen (s) + 1); } void UchChannel :: WriteBuf (const byte* b, int n) { Write (b, n); } bool UchChannel :: ReadLong (lword& l) { return bool (Read ((byte*)&l, lwsize) == lwsize); } bool UchChannel :: ReadShort (sword& s) { return bool (Read ((byte*)&s, swsize) == swsize); } bool UchChannel :: ReadByte (byte& b) { return bool (Read (&b, 1) == 1); } bool UchChannel :: ReadChar (char& c) { return bool (Read ((byte*)&c, 1) == 1); } int UchChannel :: ReadString (char* s, int n) { int i = 0; // this is extremely non optimal do { Read ((byte*)s, 1); i++; } while (*s++ && n--); return i; } int UchChannel :: ReadString (CcuString& s) { // this enforces an undue limitation char c [1024]; int i = ReadString (c, -1); s = c; return i; } bool UchChannel :: ReadBuf (byte* b, int n) { return bool (Read (b, n) == n); }