[ceph.git] / ceph / src / boost / libs / fiber / doc / promise.qbk

[/
          Copyright Oliver Kowalke 2013.
 Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at
          http://www.boost.org/LICENSE_1_0.txt
]

[#class_promise]
[section:promise Template `promise<>`]

A __promise__ provides a mechanism to store a value (or exception) that can
later be retrieved from the corresponding __future__ object. `promise<>` and
`future<>` communicate via their underlying [link shared_state shared state].

        #include <boost/fiber/future/promise.hpp>

        namespace boost {
        namespace fibers {

        template< typename R >
        class promise {
        public:
            promise();

            template< typename __Allocator__ >
            promise( __allocator_arg_t__, Allocator);

            promise( promise &&) noexcept;

            promise & operator=( promise &&) noexcept;

            promise( promise const&) = delete;

            promise & operator=( promise const&) = delete;

            ~promise();

            void swap( promise &) noexcept;

            future< R > get_future();

            void set_value( R const&);  // member only of generic promise template
            void set_value( R &&);      // member only of generic promise template
            void set_value( R &);       // member only of promise< R & > template
            void set_value();           // member only of promise< void > template

            void set_exception( std::exception_ptr p);
        };

        template< typename R >
        void swap( promise< R > &, promise< R > &) noexcept;

        }

[heading Default constructor]

        promise();

[variablelist
[[Effects:] [Creates a promise with an empty [link shared_state shared state].]]
[[Throws:] [Exceptions caused by memory allocation.]]
]

[heading Constructor]

        template< typename __Allocator__ >
        promise( __allocator_arg_t__, Allocator alloc);

[variablelist
[[Effects:] [Creates a promise with an empty [link shared_state shared state] by using `alloc`.]]
[[Throws:] [Exceptions caused by memory allocation.]]
[[See also:] [__allocator_arg_t__]]
]

[heading Move constructor]

        promise( promise && other) noexcept;

[variablelist
[[Effects:] [Creates a promise by moving the [link shared_state shared state] from `other`.]]
[[Postcondition:] [`other` contains no valid shared state.]]
[[Throws:] [Nothing.]]
]

[heading Destructor]

        ~promise();

[variablelist
[[Effects:] [Destroys `*this` and abandons the [link shared_state shared
state] if shared state is ready; otherwise stores __future_error__ with error
condition __broken_promise__ as if by [member_link promise..set_exception]:
the shared state is set ready.]]
]

[operator_heading promise..operator_assign..operator=]

        promise & operator=( promise && other) noexcept;

[variablelist
[[Effects:] [Transfers the ownership of [link shared_state shared state] to `*this`.]]
[[Postcondition:] [`other` contains no valid shared state.]]
[[Throws:] [Nothing.]]
]

[member_heading promise..swap]

        void swap( promise & other) noexcept;

[variablelist
[[Effects:] [Swaps the [link shared_state shared state] between other and `*this`.]]
[[Throws:] [Nothing.]]
]

[member_heading promise..get_future]

        future< R > get_future();

[variablelist
[[Returns:] [A __future__ with the same [link shared_state shared state].]]
[[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
]

[member_heading promise..set_value]

        void set_value( R const& value);  // member only of generic promise template
        void set_value( R && value);      // member only of generic promise template
        void set_value( R & value);       // member only of promise< R & > template
        void set_value();                 // member only of promise< void > template

[variablelist
[[Effects:] [Store the result in the [link shared_state shared state] and marks the state as ready.]]
[[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]]
]

[member_heading promise..set_exception]

        void set_exception( std::exception_ptr);

[variablelist
[[Effects:] [Store an exception pointer in the [link shared_state shared state] and marks the state as ready.]]
[[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]]
]

[function_heading_for swap..promise]

    template< typename R >
    void swap( promise< R > & l, promise< R > & r) noexcept;

[variablelist
[[Effects:] [Same as `l.swap( r)`.]]
]

[endsect]
Commit	Line	Data
7c673cae FG	1	[/
	2	Copyright Oliver Kowalke 2013.
	3	Distributed under the Boost Software License, Version 1.0.
	4	(See accompanying file LICENSE_1_0.txt or copy at
	5	http://www.boost.org/LICENSE_1_0.txt
	6	]
	7
	8	[#class_promise]
	9	[section:promise Template `promise<>`]
	10
	11	A __promise__ provides a mechanism to store a value (or exception) that can
	12	later be retrieved from the corresponding __future__ object. `promise<>` and
	13	`future<>` communicate via their underlying [link shared_state shared state].
	14
	15	#include <boost/fiber/future/promise.hpp>
	16
	17	namespace boost {
	18	namespace fibers {
	19
	20	template< typename R >
	21	class promise {
	22	public:
	23	promise();
	24
	25	template< typename __Allocator__ >
	26	promise( __allocator_arg_t__, Allocator);
	27
	28	promise( promise &&) noexcept;
	29
	30	promise & operator=( promise &&) noexcept;
	31
	32	promise( promise const&) = delete;
	33
	34	promise & operator=( promise const&) = delete;
	35
	36	~promise();
	37
	38	void swap( promise &) noexcept;
	39
	40	future< R > get_future();
	41
	42	void set_value( R const&); // member only of generic promise template
	43	void set_value( R &&); // member only of generic promise template
	44	void set_value( R &); // member only of promise< R & > template
	45	void set_value(); // member only of promise< void > template
	46
	47	void set_exception( std::exception_ptr p);
	48	};
	49
	50	template< typename R >
	51	void swap( promise< R > &, promise< R > &) noexcept;
	52
	53	}
	54
	55	[heading Default constructor]
	56
	57	promise();
	58
	59	[variablelist
	60	[[Effects:] [Creates a promise with an empty [link shared_state shared state].]]
	61	[[Throws:] [Exceptions caused by memory allocation.]]
	62	]
	63
	64	[heading Constructor]
65
66	template< typename __Allocator__ >
67	promise( __allocator_arg_t__, Allocator alloc);
68
69	[variablelist
70	[[Effects:] [Creates a promise with an empty [link shared_state shared state] by using `alloc`.]]
71	[[Throws:] [Exceptions caused by memory allocation.]]
72	[[See also:] [__allocator_arg_t__]]
73	]
74
75	[heading Move constructor]
76
77	promise( promise && other) noexcept;
78
79	[variablelist
80	[[Effects:] [Creates a promise by moving the [link shared_state shared state] from `other`.]]
81	[[Postcondition:] [`other` contains no valid shared state.]]
82	[[Throws:] [Nothing.]]
83	]
84
85	[heading Destructor]
86
87	~promise();
88
89	[variablelist
90	[[Effects:] [Destroys `*this` and abandons the [link shared_state shared
91	state] if shared state is ready; otherwise stores __future_error__ with error
92	condition __broken_promise__ as if by [member_link promise..set_exception]:
93	the shared state is set ready.]]
94	]
95
96	[operator_heading promise..operator_assign..operator=]
97
98	promise & operator=( promise && other) noexcept;
99
100	[variablelist
101	[[Effects:] [Transfers the ownership of [link shared_state shared state] to `*this`.]]
102	[[Postcondition:] [`other` contains no valid shared state.]]
103	[[Throws:] [Nothing.]]
104	]
105
106	[member_heading promise..swap]
107
108	void swap( promise & other) noexcept;
109
110	[variablelist
111	[[Effects:] [Swaps the [link shared_state shared state] between other and `*this`.]]
112	[[Throws:] [Nothing.]]
113	]
114
115	[member_heading promise..get_future]
116
117	future< R > get_future();
118
119	[variablelist
120	[[Returns:] [A __future__ with the same [link shared_state shared state].]]
121	[[Throws:] [__future_error__ with __already_retrieved__ or __no_state__.]]
122	]
123
124	[member_heading promise..set_value]
125
126	void set_value( R const& value); // member only of generic promise template
127	void set_value( R && value); // member only of generic promise template
128	void set_value( R & value); // member only of promise< R & > template
129	void set_value(); // member only of promise< void > template
130
131	[variablelist
132	[[Effects:] [Store the result in the [link shared_state shared state] and marks the state as ready.]]
133	[[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]]
134	]
135
136	[member_heading promise..set_exception]
137
138	void set_exception( std::exception_ptr);
139
140	[variablelist
141	[[Effects:] [Store an exception pointer in the [link shared_state shared state] and marks the state as ready.]]
142	[[Throws:] [__future_error__ with __already_satisfied__ or __no_state__.]]
143	]
144
145	[function_heading_for swap..promise]
146
147	template< typename R >
148	void swap( promise< R > & l, promise< R > & r) noexcept;
149
150	[variablelist
151	[[Effects:] [Same as `l.swap( r)`.]]
152	]
153
154	[endsect]