rbb 99/02/16 04:57:00
Added: docs impl.txt
Log:
A first stab at some implementation suggestions for APR types. The only
one I have really thought about is the APRFile, but I am putting the rest
out as well. Everybody have a look and make some comments.
Revision Changes Path
1.1 apache-apr/docs/impl.txt
Index: impl.txt
===================================================================
---------------------------Suggested implementations of Types
APRIint16, APRInt32, APRUInt32, etc.
Proper sized (Un)signed or integers where APRU signifies unsigned, and
the integer is the number of bytes.
APRINTN
Native Integers
For right now, assume these are staying in. If we decide against them,
they will all be replaced with an integer size that makes sense. Right
now, I don't want to change them all.
APRFile
Windows: Handle.
UNIX: structure {
APRINT file descriptor
FILE * file pointer
char * name
int mode
int user id
int group id
APTime access time
APTime modified time
APTime change time
}
Basically, the File structure stores all the stat
information
about the structure. This allows us to only open the
file, stat
it, and use the file if we are serving a page. We do
not need
to stat it more than once. However, we provide the
stat function,
because other types of programs may need it. For
example, a database
should not rely upon the data in a APRFile variable to
be kept up to
date. It is provided to help us "cheat" whenever
possible.
We have a file pointer and a file descriptor, because
this is an easy
way to determine if the output is buffered or not. We
could do this
with a simple boolean flag, it doesn't really metter
to me.
APRSocket in the future. */
APRInt32
APRLock /* A generic lock, not a mutex or a condition
variable, just a generic way to lock the
thread/process. (Not Apache centric, but
a useful function.)
IF PTHREADS
1) mutex: pthread_mutex_t; the actual lock
2) notified: Notified_node; array of conditions notified
3) owner: pthread_t; current owner of lock.
ELSE
We will define this later, because all initial platforms have pthreads.
Notified_node
1) lenght: APRINTN; # of entries in this node.
Array of abstracted size of:
1) condvar: APRCond; condition variable notified
2) numtimes: APRINTN; number of times notified
2) next: Notified_node; next one of these in list.
APRCOND
1) lock: APRLock; underlying APRLock
2) cond: pthread_cond_t; pthreads condition
3) notify_pending: APRINTN; cond has pending notification
APRTime
APRINT64
APRStatus
APRInt32
APRERRORCODE
APRInt32
APR_EXPORT
Should be able to use same def as APRI_EXPORT
APR_NETDB_BUF_SIZE
size of host entry table.
APRDIR
1) dir name: char *
2) dir structure: OS specific. On UNIX => DIR
APRIOVec
1) base addr: void *; starting point in memory of data
2) len: APRInt32; length of data.
APRFileInfo
1) type: APRFileType; enumerated type see below
2) size: APRUInt32; size in bytes of file
3) creation time: APRTime; Creation time of file per def of APRTime
4) modify time: APRTime; last mod time of file per def of APRTime
APRFileType
enumerated type
APRFILE: It's a file
APRDIRECTORY: It's a directory
APROTHER: It's something else, ex: pipe
APRSeekWhere
enumerated type
APR_SEEK_SET Set's file pointer to offset parameter
APR_SEEK_CUR Set's file pointer to current position
plus offset
APR_SEEK_END Set's file pointer to end of file
APR_MAX_IOVEC_SIZE
APRInt32
Maximum size for APRIOVec array. For right now, let's make it 16, but
we can change it later.
APRTHDPRIV
void *
APRNetAddrValue
enumerated type
APR_IpAddrNull do not overswrite the IP addr.
APR_IpAddrAny INADDR_ANY equivalent
APR_IpAddrLoopback INADDR_LOOPBACK equivalent
APRNetAddr
1) family: APRUInt16; Address Family
2) port: APRUInt16; port
3) ip: APRUInt32; the 32 bit ip address
APRHostEnt
1) name: char *; name of host
2) aliases: char **; list of aliases
3) addrtype: Win=> APRInt16 Unix=> APRInt32; host addr type
4) length: Win=> APRInt16 Unix=>APRInt32; length of addr
5) addr_list: char *; list of addr's from Name Server
APRSocketOptionData
APRInt32
1) APR_SockOpt_NoDelay
2) APR_SockOpt_Reuseaddr
3) APR_SockOpt_SendBufferSize
4) APR_SockOpt_Keepalive
5) APR_SockOpt_Linger
APRPollDesc
1) fdarr: APRFile; Array of File Desc's to check.
2) events: APRInt16; events to look for.
3) retevents: APRInt16; events that were triggered.
APRTimeParametersFn
function which when given a time instant in GMT, returns the timezone
information. We need to implement one function for GMT and one for
local timezones. This allows us to generalize changes in DST.
APRTHDDESTFN
function which de-allocates thread-private data.
APRExplodedTime
1) year: APRInt32; store in 4 digit format to avoid y2k bugs.
2) month: APRInt32; # of months into year [0,11]
3) mday: APRInt32; day of month [1, 31]
4) hour: APRInt32; hours into the day [0, 24]
5) min: APRInt32; minutes into the hour [0,60]
6) sec: APRInt32; seconds into the min [0,0]
7) params: APRTimeParametersFn; local timezone info.
Not needed when giving Exp time as input, but nice if we should add
them when creating output
9) wday: APRInt32; day of week [0,6]
10) yday: APRInt32; day of year [0,365 | 366 (leAPR year)]
APRTHREADTYPE
enumerated type
APR_USER_THREAD
APR_SYSTEM_THREAD
APRTHREADPriority
enumerated type
APR_PRIORITY_FIRST placeholder
APR_PRIORITY_LOW the lowest possible priority
APR_PRIORITY_NORMAL most common expected priority
APR_PRIORITY_HIGH slightly more aggressive scheduling
APR_PRIORITY_URGENT no sense to have more than one
APR_PRIORITY_LAST placeholder
APRTHREADScope
enumerated type
APR_LOCAL_THREAD
APR_GLOBAL_THREAD
APRTHREADState
enumerated type
APR_JOINABLE_THREAD,
APR_UNJOINABLE_THREAD
APRProcess
1) pid: UNIX=> pid_t;OS specific process id.
APRPROCESSATTR
1) stdinFd: APRFile *
2) stdoutFd: APRFile *
3) stderrFd: APRFile *
4) currdir: char * ; current directory.
APRPrimaryFn
(APRINTN *)(APRINTN, char **)
APRShutdownHow
enumerated type
APR_SHUTDOWN_RCV Further receives not allowed.
APR_SHUTDOWN_SEND Further sends not allowed.
APR_SHUTDOWN_BOTH Further sends and receives not allowed.
APRSYSINFO
enumerated type
APR_SI_HOSTNAME get name of the host
APR_SI_SYSNAME get name of the system
APR_SI_RELEASE get release number of the system
APR_SI_ARCHITECTURE get architecture of the system
APRFilePerms
enumerated type
APR_ACCESS_READ_OK Test for read permission.
APR_ACCESS_WRITE_OK Test for write permission.
APR_ACCESS_EXISTS Check existence of file.
DPRINTF
debug printf. (Only print arguement if in debug mode)
APRTHREAD
1) state: APRUInt32; thread's creation state
2) priority: APRTHREADPriority; APRparent priority, loosly defined
3) errstrsize: APRInt32; byte length of current error string | zero
4) errorCode; APRErrorCode; current APR error code | zero
5) osErrorCode: APRInt32; mAPRping of errorCode | zero
6) errorString: char *; current error string | NULL
7) arg: void *; argument to the client's entry point
8) startfunc: (void *)(void *arg); the root of the client's thread
9) stack: APRTHREADStack; info about thread's stack (for GC)
10) environment: void *; pointer to execution environment
11) dump: APRTHREADDumpProc; dump thread info out
12) dumpArg: void *; argument for the dump function
If PThreads defined
13) id:pthread_t;pthread identifier for the thread
14) okToDelete: APRBool; ok to delete the APRTHREAD struct?
15) io_cv: APRCondVar *;a condition used to run i/o
16) waiting: APRCondVar *; where the thread is waiting | NULL
17) sp: void *;recorded sp for garbage collection
18) next, prev: APRTHREAD *; simple linked list of all threads
19) suspend: APRUInt32;used to store suspend and resume flags
APRBool
APRInt16 nly valid values are 1 and 0.
No decision how to implement yet.
APRTHREADPROCDUMP
APRFILEPERMS
Events
APRPOLL_READ: File descriptor is readable
APRPOLL_WRITE: File descriptor is writable
APRPOLL_EXCEPT: File descriptor has an exception
APRPOLL_ERROR: File descriptor has an error
APRPOLL_INVALID: File descriptor is invalid
Timing Defines
DEFAULT_TIMEOUT: default timeout value
DEFAULT_KEEPALIVE_TIMEOUT: default value for keepalive connections
