wy__dirhandle.h

一个不错

/* Copyright is licensed under GNU LGPL.                 by I.J.Wang 2003
*/

#ifndef WY__DIRHANDLE_H__
#define WY__DIRHANDLE_H__
#define WY__DIRHANDLE_VERSION 31

#include "wymutex.h"
#include "wyfilehandle.h"
#include "wyfilestat.h"
#include "wydirent.h"
#include "wy_array.h"
#include <sys/types.h>
#include <dirent.h>

// [Internal] Wy__DirHandEnt defines the class of system directory handle.
//            This class exists because no dup/fstat equivalent 
//            operation for ::DIR* as with file descriptor
//
// Note: None of members are cancelable
//
class Wy__DirHandEnt {
  public:
    // [Syn] Construct default object 
    //       (ref_count() == 0)
    //
    Wy__DirHandEnt() WY__TSPC()
              : _rcnt(0) {};

    // [Syn] Construct object by copy  (only default object)
    //
    // Note: This constructor is for Wy_Array to expand size.
    //       Copy source must be default.
    //       No two Wy__DirHandEnt objects can be copied except the default
    //       ones.
    //
    Wy__DirHandEnt(const Wy__DirHandEnt& src) WY__TSPC();

    Wy__DirHandEnt(Wy__DirHandEnt& src, Wy::ByMove_t) WY__TSPC()
         {
           _rcnt=src._rcnt;
           _dirp=src._dirp;
           _fd  =src._fd;

           // mark for safety
           src._rcnt=0;
           src._dirp=NULL;
           src._fd=-1;
         };

    // [Syn] Destroy object
    //
    //  Note: reset error is ignored
    //
    ~Wy__DirHandEnt() WY__TSPC()
              { _reset(); };

    // [Syn] is object the state as default constructed
    //
    // [Ret] true  = object is the same as default constructed, 
    //       false = otherwise
    //
    bool is_default(void) const WY__NOTHROW__
              { return _rcnt==0; };

    // [Syn] Open the object from the directory dirname and set the reference
    //       count to one.
    //
    // [Ret] Ok 
    //       Wym_EACCES not a default object (added by this library,
    //                  app. should not get this)
    //       Wym_EACCES search permission is denied
    //       Wym_ENAMETOOLONG pathname too long
    //       Wym_ENOENT pathname does not exist
    //       Wym_ENOTDIR a component in pathname is not a directory
    //       Wym_EMFILE too many open fd
    //       Wym_ENFILE file table overflow
    //       Wym_ENOMEM not enough memory
    //       ...        reply converted from ::opendir(...) or open(int)
    //
    WyRet open(const char* dirname);

    // [Syn] Check in the use of the object and increase the reference count
    //       by one. The object should have been open to call this function.
    //
    // [Ret] Ok         reference of the object counted
    //       Wym_ENOENT object is not open yet
    //       Wym_ENFILE counter overflow
    //
    WyRet check_in(void) WY__TSPC();

    // [Syn] Check out the use of the object and decrease the reference count
    //       by one. If the reference count reaches zero, the object is reset.
    //
    // [Ret] Ok
    //       Wym_ENOENT object is default
    //       Wym_EIO   Input/output error 
    //       ...       reply converted from the call of ::closedir(...)
    //
    // Note: failed or not, reference count is decreased by one (until zero).
    //
    WyRet check_out(void) WY__TSPC();

    // [Syn] Get the ::DIR pointer of this object
    //
    // [Ret] ::DIR pointer of this object
    //
    // Note: The returned value is valid while object is open or checked-in.
    //       And is dedicated for use by readdir/rewind
    //
    inline ::DIR* dirp(void) WY__NOTHROW__
              { return _dirp; };

    // [Syn] Get the file descriptor of this object
    //
    // [Ret] file descriptor of this object
    //
    // Note: The returned value is valid while object is open or checked-in.
    //       And is dedicated for use by fstat
    //
    inline Wy__TypeFD fd(void) WY__NOTHROW__
              { return _fd; };

    // [Syn] Get the reference count
    //
    // [Ret] reference count
    //
    size_t ref_count(void) const WY__NOTHROW__
              { return _rcnt; };
      
  private:
    static const char DirNameOfEmpty[];

    // [Syn] Reset object to the default state
    //
    // [Ret] Ok
    //       Wym_EIO   Input/output error 
    //       ...       reply converted from the returned errno of closedir(...)
    //
    // Note: Object is always default while returned.
    //       EINTR is retried in the internal loop to go away
    //
    WyRet _reset(void);

    size_t _rcnt;       // reference count
    ::DIR *_dirp;       // points to the ::DIR this object is using
    Wy__TypeFD _fd;     // file descriptor this object is using
};

/*
  [Internal] Wy__DirHandle defines the class of the system directory.
*/
class Wy__DirHandle {
  public:
    static const char class_name[];
    WY_THROW_REPLY;

    // [Syn] Construct default object. (Object refers to nothing)
    //
    Wy__DirHandle() WY__TSPC()
              : _idx(DefaultIdx) {};

    // [Syn] Construct object by copy from src
    //
    // Note: The copy object associates to the same node as src does.
    //
    // [Throw] Reply
    //             Wym_ENFILE counter overflow
    // 
    // Note: This copy constructed share the same information with src
    //       Operations of one object is the same as that on the other object.
    // 
    // [Refer] ::dup(int)
    //
    Wy__DirHandle(const Wy__DirHandle&) WY__TSPC(WyRet);

    // [Syn] Destroy the object.
    //
    //  Note: reset error is ignored
    //
    // [Refer] ::closrdir(...),close(int)
    //
    ~Wy__DirHandle() WY__TSPC();

    // [Syn] is object the state as default constructed
    //
    // [Ret] true  = object is the same as default constructed, 
    //       false = otherwise
    //
    bool is_default(void) const WY__NOTHROW__
              { return _idx==DefaultIdx; };

    WyFileHandle fh(void) const WY__NOTHROW__;

    // [Syn] Read the filestat of this object and save to filestat
    //
    // [Ret] Ok    
    //       Wym_EBADF  object is default
    //       ......
    // 
    // Note: reply is converted from the errno ::fstat returned
    //       
    // [Refer] ::fstat(int,struct stat)
    // 
    WyRet fstat(WyFileStat& filestat) const;

    // [Syn] Reset the object to the state as default constructed.
    //
    // [Ret] Ok    Succeed
    //       Wym_EIO   Input/output error 
    //       ...   reply converted from the errno ::close/::closedir returned
    //
    // Note: Object is always default while returned.
    //       EINTR is retried in the internal loop to go away
    //
    // [Refer] ::closedir(...),::close(int)
    //
    WyRet reset(void);

    // [Syn] Assign object to handle the device handled by src
    //
    // [Ret] Ok         object can be used interchangeably with src
    //       Wym_ACCES object is not default 
    //                 (added by this library, app. should not get this)
    //       Wym_ENFILE counter overflow
    //
    // Note: This assigned object share the same information with src
    //       Operations of one object is the same as that on the other object.
    //
    // [Refer]
    // 
    WyRet reset(const Wy__DirHandle& src);

    void swap(Wy__DirHandle& src) WY__TSPC()
         { Wy__Base::vswap(_idx,src._idx); };

    // [Syn] Read the directory entry of the next position
    //
    // [Ret] Ok        success, dirent is stored with the directory entry read.
    //                 dirent is set to default if no more entry to read.
    //       ...       reply converted from ::readdir_r
    // 
    // Note: Multiple processes may access exactly the same directory at the
    //       same time.
    // 
    // [Refer] ::readdir_r
    // 
    WyRet read(WyDirEnt& dirent);

    // [Syn] Reset the read position
    //
    // [Ret] Ok           success
    //       Wym_BADF  object is default
    // 
    WyRet rewind(void);

    // [Syn] Open the the directory node by the given pathname (read-only)
    // 
    // [Ret] Ok         succeed
    //       Wym_EACCES object is not default
    //                 (added by this library, app. should not get this)
    //       Wym_EACCES search permission is denied
    //       Wym_EEXIST pathname already exists
    //       Wym_EINTR  interrupted by a signal
    //       Wym_EISDIR object refers to a directory
    //       Wym_EMFILE too many open fd
    //       Wym_ENAMETOOLONG pathname too long
    //       Wym_ENFILE file table overflow
    //       Wym_ENOENT pathname does not exist
    //       Wym_ENOSPC device left no space for the operation
    //       Wym_ENOTDIR a component in pathname is not a directory
    //       Wym_ENXIO  no such device (device not ready)
    //       Wym_EROFS read-only file system
    //       Wym_ENODEV no such device
    //       Wym_ETXTBSY Text file busy (see man.)
    //       Wym_EFAULT pathname is not accessible
    //       Wym_ELOOP too many symbolic links encountered
    //       Wym_ENOMEM not enough memory
    //       ...        reply converted from the errno ::opendir and ::open(...)
    //                  returned
    //
    // [Refer] ::opendir(const char*),::open(...)
    //
    WyRet open(const char* dirname);
    WyRet open(const WyStr& dirname);

    //
    // [Internal]
    //
    size_t ref_count(void) const;
  private:
    enum { DefaultIdx=-1 };

    // Handle table
    static Wy_Array<Wy__DirHandEnt> wy_tab; 
    static WyMutex wy_tab_mtx;            

    int _idx;   // index of the entry in wy_tab
};

#endif