// This may look like C code, but it's really -*- C++ -*-
/*
 * Copyright (C) 2009 Emweb bvba, Kessel-Lo, Belgium.
 *
 * See the LICENSE file for terms of use.
 */
#ifndef HTTP_RESPONSE_CONTINUATION_H_
#define HTTP_RESPONSE_CONTINUATION_H_

#include <Wt/WGlobal>
#include <boost/any.hpp>

#include <boost/shared_ptr.hpp>
#include <boost/enable_shared_from_this.hpp>

namespace boost {
  class recursive_mutex;
}

namespace Wt {

  class WResource;
  class WebResponse;
  class WebSession;

  namespace Http {

    class Response;

/*! \class ResponseContinuation Wt/Http/ResponseContinuation Wt/Http/ResponseContinuation
 *  \brief A resource response continuation object.
 *
 * A response continuation object is used to keep track of a response
 * which is to be continued.
 *
 * You may associate data with the object using setData().
 *
 * A continuation is used to resume sending more data later for this
 * response. There are two possible reasons for this:
 * - the entire response is quite big and you may want to read and send
 *   it in smaller chunks. This avoids unbounded memory usage since the
 *   I/O layer buffers the response first in memory to send it then out
 *   to a possibly slow client using async I/O.
 * - you may not have any more data available, currently, but expect more
 *   data later. In that case you can call waitForMoreData() and later call
 *   WResource::haveMoreData() when more data is available.
 *
 * \sa Response::createContinuation(), Request::continuation()
 *
 * \ingroup http
 */
class WT_API ResponseContinuation 
  : public boost::enable_shared_from_this<ResponseContinuation>
{
public:
  ~ResponseContinuation();

  /*! \brief Set data associated with the continuation.
   *
   * You could do this to keep track of the state of sending the data
   * for a WResource.
   */
  void setData(const boost::any& data);

  /*! \brief Return data associated with the continuation.
   *
   * \sa setData()
   */
  boost::any data() { return data_; }

  /*! \brief Return the resource.
   */
  WResource *resource() const { return resource_; }

  /*! \brief Wait for more data.
   *
   * This suspends the handling of this request until more data is
   * available, indicated with a call to haveMoreData(), or to a
   * resource globally using WResource::haveMoreData().
   */
  void waitForMoreData();

  /*! \brief Indicates that we have more data.
   *
   * This will allow the response to be resumed with a new call to
   * WResource::handleRequest().
   */
  void haveMoreData();

  /*! \brief Returns whether this continuation is waiting for data.
   *
   * \sa waitForMoreData()
   */
  bool isWaitingForMoreData() const { return waiting_; }

private:
#ifdef WT_THREADED
  boost::shared_ptr<boost::recursive_mutex> mutex_;
#endif

  WResource *resource_;
  WebResponse *response_;
  boost::any data_;
  bool waiting_, readyToContinue_;

  ResponseContinuation(WResource *resource, WebResponse *response);
  ResponseContinuation(const ResponseContinuation&);

  void cancel(bool resourceIsBeingDeleted);
  void readyToContinue(WebWriteEvent writeResult);

  WebResponse *response() { return response_; }

  friend class Wt::WResource;
  friend class Wt::WebSession;
  friend class Response;
};

typedef boost::shared_ptr<ResponseContinuation> ResponseContinuationPtr;

  }
}

#endif // HTTP_RESPONSE_CONTINUATION_H_
