← Back to branch summary

~ubuntu-branches/ubuntu/intrepid/miro/intrepid

« back to all changes in this revision

Viewing changes to portable/libtorrent/include/libtorrent/asio/strand.hpp

  • Committer: Bazaar Package Importer
  • Author(s): Christopher James Halse Rogers
  • Date: 2008-02-09 13:37:10 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20080209133710-9rs90q6gckvp1b6i
Tags: 1.1.2-0ubuntu1
New upstream release

Show diffs side-by-side

added added

removed removed

Lines of Context:
portable/libtorrent/include/libtorrent/asio/strand.hpp
 
1
//
 
2
// strand.hpp
 
3
// ~~~~~~~~~~
 
4
//
 
5
// Copyright (c) 2003-2007 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 
6
//
 
7
// Distributed under the Boost Software License, Version 1.0. (See accompanying
 
8
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
9
//
 
10
 
 
11
#ifndef ASIO_STRAND_HPP
 
12
#define ASIO_STRAND_HPP
 
13
 
 
14
#if defined(_MSC_VER) && (_MSC_VER >= 1200)
 
15
# pragma once
 
16
#endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
 
17
 
 
18
#include "asio/detail/push_options.hpp"
 
19
 
 
20
#include "asio/io_service.hpp"
 
21
#include "asio/detail/strand_service.hpp"
 
22
#include "asio/detail/wrapped_handler.hpp"
 
23
 
 
24
namespace asio {
 
25
 
 
26
/// Provides serialised handler execution.
 
27
/**
 
28
 * The io_service::strand class provides the ability to post and dispatch
 
29
 * handlers with the guarantee that none of those handlers will execute
 
30
 * concurrently.
 
31
 *
 
32
 * @par Thread Safety
 
33
 * @e Distinct @e objects: Safe.@n
 
34
 * @e Shared @e objects: Safe.
 
35
 *
 
36
 * @par Concepts:
 
37
 * Dispatcher.
 
38
 */
 
39
class io_service::strand
 
40
{
 
41
public:
 
42
  /// Constructor.
 
43
  /**
 
44
   * Constructs the strand.
 
45
   *
 
46
   * @param io_service The io_service object that the strand will use to
 
47
   * dispatch handlers that are ready to be run.
 
48
   */
 
49
  explicit strand(asio::io_service& io_service)
 
50
    : service_(asio::use_service<
 
51
        asio::detail::strand_service>(io_service))
 
52
  {
 
53
    service_.construct(impl_);
 
54
  }
 
55
 
 
56
  /// Destructor.
 
57
  /**
 
58
   * Destroys a strand.
 
59
   *
 
60
   * Handlers posted through the strand that have not yet been invoked will
 
61
   * still be dispatched in a way that meets the guarantee of non-concurrency.
 
62
   */
 
63
  ~strand()
 
64
  {
 
65
    service_.destroy(impl_);
 
66
  }
 
67
 
 
68
  /// Get the io_service associated with the strand.
 
69
  /**
 
70
   * This function may be used to obtain the io_service object that the strand
 
71
   * uses to dispatch handlers for asynchronous operations.
 
72
   *
 
73
   * @return A reference to the io_service object that the strand will use to
 
74
   * dispatch handlers. Ownership is not transferred to the caller.
 
75
   */
 
76
  asio::io_service& io_service()
 
77
  {
 
78
    return service_.io_service();
 
79
  }
 
80
 
 
81
  /// Request the strand to invoke the given handler.
 
82
  /**
 
83
   * This function is used to ask the strand to execute the given handler.
 
84
   *
 
85
   * The strand object guarantees that handlers posted or dispatched through
 
86
   * the strand will not be executed concurrently. The handler may be executed
 
87
   * inside this function if the guarantee can be met. If this function is
 
88
   * called from within a handler that was posted or dispatched through the same
 
89
   * strand, then the new handler will be executed immediately.
 
90
   *
 
91
   * The strand's guarantee is in addition to the guarantee provided by the
 
92
   * underlying io_service. The io_service guarantees that the handler will only
 
93
   * be called in a thread in which the io_service's run member function is
 
94
   * currently being invoked.
 
95
   *
 
96
   * @param handler The handler to be called. The strand will make a copy of the
 
97
   * handler object as required. The function signature of the handler must be:
 
98
   * @code void handler(); @endcode
 
99
   */
 
100
  template <typename Handler>
 
101
  void dispatch(Handler handler)
 
102
  {
 
103
    service_.dispatch(impl_, handler);
 
104
  }
 
105
 
 
106
  /// Request the strand to invoke the given handler and return
 
107
  /// immediately.
 
108
  /**
 
109
   * This function is used to ask the strand to execute the given handler, but
 
110
   * without allowing the strand to call the handler from inside this function.
 
111
   *
 
112
   * The strand object guarantees that handlers posted or dispatched through
 
113
   * the strand will not be executed concurrently. The strand's guarantee is in
 
114
   * addition to the guarantee provided by the underlying io_service. The
 
115
   * io_service guarantees that the handler will only be called in a thread in
 
116
   * which the io_service's run member function is currently being invoked.
 
117
   *
 
118
   * @param handler The handler to be called. The strand will make a copy of the
 
119
   * handler object as required. The function signature of the handler must be:
 
120
   * @code void handler(); @endcode
 
121
   */
 
122
  template <typename Handler>
 
123
  void post(Handler handler)
 
124
  {
 
125
    service_.post(impl_, handler);
 
126
  }
 
127
 
 
128
  /// Create a new handler that automatically dispatches the wrapped handler
 
129
  /// on the strand.
 
130
  /**
 
131
   * This function is used to create a new handler function object that, when
 
132
   * invoked, will automatically pass the wrapped handler to the strand's
 
133
   * dispatch function.
 
134
   *
 
135
   * @param handler The handler to be wrapped. The strand will make a copy of
 
136
   * the handler object as required. The function signature of the handler must
 
137
   * be: @code void handler(A1 a1, ... An an); @endcode
 
138
   *
 
139
   * @return A function object that, when invoked, passes the wrapped handler to
 
140
   * the strand's dispatch function. Given a function object with the signature:
 
141
   * @code R f(A1 a1, ... An an); @endcode
 
142
   * If this function object is passed to the wrap function like so:
 
143
   * @code strand.wrap(f); @endcode
 
144
   * then the return value is a function object with the signature
 
145
   * @code void g(A1 a1, ... An an); @endcode
 
146
   * that, when invoked, executes code equivalent to:
 
147
   * @code strand.dispatch(boost::bind(f, a1, ... an)); @endcode
 
148
   */
 
149
  template <typename Handler>
 
150
#if defined(GENERATING_DOCUMENTATION)
 
151
  unspecified
 
152
#else
 
153
  detail::wrapped_handler<strand, Handler>
 
154
#endif
 
155
  wrap(Handler handler)
 
156
  {
 
157
    return detail::wrapped_handler<io_service::strand, Handler>(*this, handler);
 
158
  }
 
159
 
 
160
private:
 
161
  asio::detail::strand_service& service_;
 
162
  asio::detail::strand_service::implementation_type impl_;
 
163
};
 
164
 
 
165
/// Typedef for backwards compatibility.
 
166
typedef asio::io_service::strand strand;
 
167
 
 
168
} // namespace asio
 
169
 
 
170
#include "asio/detail/pop_options.hpp"
 
171
 
 
172
#endif // ASIO_STRAND_HPP