pthread_io.3

用c++包装好的线程库,直接拿来使用,提高效率.

.\" Copyright (c) 1999-2000 Orn E. Hansen <[e-mail]>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\"                                                                            
.TH THREADS 3 "10 Feb 2000" "Threads 2.0" "Threads C++ Library"
.SH NAME
cond \- A class, for process synchronisation.
.SH SYNOPSIS
.B        #include <thread_io.h>
.sp 2
.B        ...
.sp 0
.B        class myio : public pthread_io {
.sp 0
.B          protected:
.sp 0
.B           void got(const char *,int) { /* input method */ };
.sp 1
.B          public:
.sp 0
.B           myio() : pthread_io( ... ) { };
.sp 0
.B           ~myio() { close(fd()); };
.sp 0
.B        };
.sp 0
.B        ...
.SH DESCRIPTION
The
.I pthread_io
class is a part of the threads C++ library that focuses on
simplifying program threading.

By expanding the basic thread class, a threaded IO class is
provieded that gives the programmer asynchronous functionality
through input methods in the class.  This simplifies data
input and output from sockets, as well as serial lines.

The class is an abstract class, meaning that it needs to be
a superclass to another.  Reason for this, is that the method
where input from is received needs to be filled in by the
programmer.
.LP
There are three ways in which to create a class of this
type.  Constructors are provided to manage a normal file
descriptor, that can be associated with a serial line, or
a server socket, or a client socket.

The constructors are as follows.
.TP 10
.B pthread_io()
It may be useful for a construct of this class, to manage
only outside file descriptors.  Descriptors that may be
roaming, opened for a time and closed for a time, without
being permanently managed.  In such an environment, this
constructor is useful.  No file descriptor is opened or
managed, nor can there be any server socket management.
.TP 10
.B pthread_io(int)
This constructor will manage input from the given file
descriptor.  The descriptor is not thought to be a
server socket, and therefore no client connections are
accepted to it.

Typical use for such a construction would be to manage
a serial input, such as with a modem.
.TP 10
.B pthread_io(const char *,int)
This constructor will manage input from a client socket.
The constructor is passed the name of the machine to
connect with, and the port on which the connection should
be made.

On successfull connection, the input is managed.
.TP 10
.B pthread_io(int,int)
A server socket is created, with a given port number (the
first parameter) and enabled for listening.  The last
parameter is the backlog parameter that will be passed
to the
.B listen
function.

The server socket will be manager and watched for incoming
connections, which will be reported to the
.B void open(int)
method.
.LP
The class provides numerous methods to control output to the
associated file descriptors, as well as asynchronous means
of knowing when a client has opened and closed their link
to a server socket.  Some of these methods are listed here
with explanations to their functionality.
.TP 10
.B void got(const char *,int)
This method is protected inside the class hierarchy, and
can't be accessed from the outside.  It provides the
link where all data input, coming from the associated
file descriptors are sent.  The parameters associated
with method, provide the buffer where the data is stored
and the number of bytes in the buffer.
.TP 10
.B void open(int)
In the case of a server socket, that is being maintained. This
method will be called whenever a client connects to the
server socket.  The method will be passed the file descriptor
number that was being opened.
.TP 10
.B void close(int)
When a client closes a connection to a server socket, the
file descriptor being closed will be passed to this method.
The programmer should make sure to close the file descriptor
if the original method is overwritten, or to call the
original method to take care of that task.
.TP 10
.B int put(int,char)
.TP 10
.B int put(char)
These two methods, provide means to send a character to an
associated file descriptor.  The programmer can either pass
the file descriptor the method, or only pass the character
to write.  In the first case, the file descriptor will be
checked to see if it is a descriptor being maintained by
the class, either as a main file descriptor or one associated
with a client connected to it's server socket.  If the
file descriptor is not passed to the method, then the
current client being served is thought to be the descriptor
being referred to, or the main descriptor associated with
the class in case it is not maintaining a listening socket.

In either case, data will only be put to a file descriptor that
is known to the class.

The method returns the number of bytes that were written
to the file descriptor, or -1 if an error occured.
.TP 10
.B int put(int,const char *, int)
.TP 10
.B int put(const char *, int)
These methods have the same functionality as the methods
before them.  They only differ in the parameter that is
to be written to the file descriptor in question.  In this
case, a whole string will be written, of a given length
which is represented by the last parameter.
.TP 10
.B int put(int,const string&)
.TP 10
.B int put(const string&)
Yet another version, of what can be written onto the
associated file descriptor.  This is a wrapper method,
that allows strings to be written, instead of passing
character pointers.

The method is identical to the above, except in this
instance the length of the string is stored inside the
string class, and needs not be passed to the method.
.TP 10
.B bool failure(int)
If an error occurs on a client file descriptor, this method
will receive the file descriptor where the error occurred.  The
method should return a true value, if the file descriptor
is to be closed as a result of the error, or else a true
value to have it remain open.

The standard method, returns a true value.
.TP 10
.B void register_fd(asynchronous_input *)
This method, registers a receiver for input data.  The class
.B asynchronous_input
provides the methods necessary to accept input.  It also had
a file descriptor associated with it, and all classes that
are to receive input asynchronously must inherit it.

It is possible for the method to throw an exception of type
.B pthread_io::exceptionTypes
which will occur, if one tries to register a file descriptor
that is already registered.  In which case a
.B pthread_io::NeedUnregister
will be issued.
.TP 10
.B void unregister_fd(asynchronous_input *)
A method that is the opposite to the
.B register_fd
method.  It will locate the registered class and file
descriptor in its internal tables, and remove them.  No
data will be accepted from the file descriptor past that
point.

No exceptions are generated by this method, if the
referred class doesn't exist in the tables, nothing is
done.
.LP
Suggestions and questions about the threads library should be
directed to:
.IP
[e-mail]

.LP
Or, to the author specified below.  The threads home page is located at:
.IP
http://user.tninet.se/~dpn659b/threads.html
.LP
.SH AUTHOR
Version 2.0
Copyright (C) 1999-2000 Orn E. Hansen <[e-mail]>.
.LP
Thanks to those who reported their suggestions on how to
improve the threads library.