X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Scheduler%2FWriteHelper.hh;h=998ae79f746364df90fd9a6c56dacf4acbf16117;hb=9a988902090d28007578e93bffd809f6bd913155;hp=f22cbfe3bb624ff1f24970858700fb31603ea3f8;hpb=ac6a813d9d99f7add4e13aff7a4bcd314d5604a6;p=senf.git

diff --git a/Scheduler/WriteHelper.hh b/Scheduler/WriteHelper.hh
index f22cbfe..998ae79 100644
--- a/Scheduler/WriteHelper.hh
+++ b/Scheduler/WriteHelper.hh
@@ -1,6 +1,25 @@
 // $Id$
 //
-// Copyright (C) 2006 
+// Copyright (C) 2006 Stefan Bund <g0dil@berlios.de>
+//
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation; either version 2 of the License, or
+// (at your option) any later version.
+//
+// This program 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 General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with this program; if not, write to the
+// Free Software Foundation, Inc.,
+// 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+// Copyright (C) 2006
+
+/** \file
+    \brief WriteHelper public header */
 
 #ifndef HH_WriteHelper_
 #define HH_WriteHelper_ 1
@@ -17,52 +36,77 @@
 
 namespace senf {
 
+    /** \brief Asyncronous writing helper
+
+        This class provides a simple asynchronous writing facility. This helper will register with
+        the Scheduler to write the requested data. It will stay registered until the data has been
+        completely sent or some error condition is encountered. As soon as the WriteHelper is done,
+        the callback will be called.
+
+        The WriteHelper accepts the same flexible file handle interfaces as the Scheduler.
+
+        The callback must take a WriteHelper::ptr argument. Using this WriteHelper instance, the
+        callback can access the state information and check the termination status.
 
+        \todo Add additional interface to better access the intermediate status (data sent so far)
+     */
     template <class Handle>
     class WriteHelper
-	: public senf::intrusive_refcount
+        : public senf::intrusive_refcount
     {
     public:
         ///////////////////////////////////////////////////////////////////////////
         // Types
 
-	typedef boost::intrusive_ptr<WriteHelper> ptr;
-	typedef boost::function<void (ptr)> Callback;
+        typedef boost::intrusive_ptr<WriteHelper> ptr; ///< Smart pointer type for this class
+        typedef boost::function<void (ptr)> Callback; ///< Callback type
 
         ///////////////////////////////////////////////////////////////////////////
         ///\name Structors and default members
         ///@{
 
-	static ptr dispatch(Handle handle, std::string data, Callback callback);
+        static ptr dispatch(Handle handle, std::string data, Callback callback);
+                                        ///< Register new WriteHelper instance
+                                        /**< The registered callback will be called after all \a
+                                             data has been sent or when some error condition is
+                                             encountered.
+                                             \param[in] handle file descriptor or handle providing
+                                                 the Handle interface defined above.
+                                             \param[in] data data to send
+                                             \param[in] cb callback
+                                             \returns smart pointer to new WriteHelper instance */
 
         ///@}
         ///////////////////////////////////////////////////////////////////////////
 
-	Handle handle() const;
+        Handle handle() const;
 
-	std::string const & data() const;
+        std::string const & data() const; ///< Return the data
+                                        /**< After all data has been sent, this member will return
+                                             an empty string. Until then, the complete string will
+                                             be returned. */
 
-	bool complete() const;
-	bool error() const;
-	void throw_error() const;
+        bool complete() const;          ///< Check whether the write has completed successfully
+        bool error() const;             ///< Check for error condition
+        void throw_error() const;       ///< If an error occurred, throw it
 
-	void revoke();
+        void revoke();                  ///< Remove the WriteHelper from the scheduler
 
     protected:
 
     private:
-	WriteHelper(Handle handle, std::string data, Callback callback);
+        WriteHelper(Handle handle, std::string data, Callback callback);
 
-	static void dispatchProcess(ptr helper, Handle handle, senf::Scheduler::EventId event);
-	void process(Handle handle, senf::Scheduler::EventId event);
-	void done();
+        static void dispatchProcess(ptr helper, Handle handle, senf::Scheduler::EventId event);
+        void process(Handle handle, senf::Scheduler::EventId event);
+        void done();
 
-	Handle handle_;
-	mutable std::string data_;
-	Callback callback_;
+        Handle handle_;
+        mutable std::string data_;
+        Callback callback_;
 
-	mutable std::string::size_type offset_;
-	int errno_;
+        mutable std::string::size_type offset_;
+        int errno_;
     };
 
 
@@ -78,4 +122,8 @@ namespace senf {
 
 // Local Variables:
 // mode: c++
+// fill-column: 100
+// c-file-style: "senf"
+// indent-tabs-mode: nil
+// ispell-local-dictionary: "american"
 // End: