Subversion
exception.hpp
Go to the documentation of this file.
1 /**
2  * @file svnxx/exception.hpp
3  * @copyright
4  * ====================================================================
5  * Licensed to the Apache Software Foundation (ASF) under one
6  * or more contributor license agreements. See the NOTICE file
7  * distributed with this work for additional information
8  * regarding copyright ownership. The ASF licenses this file
9  * to you under the Apache License, Version 2.0 (the
10  * "License"); you may not use this file except in compliance
11  * with the License. You may obtain a copy of the License at
12  *
13  * http://www.apache.org/licenses/LICENSE-2.0
14  *
15  * Unless required by applicable law or agreed to in writing,
16  * software distributed under the License is distributed on an
17  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18  * KIND, either express or implied. See the License for the
19  * specific language governing permissions and limitations
20  * under the License.
21  * ====================================================================
22  * @endcopyright
23  */
24 
25 #ifndef SVNXX_EXCEPTION_HPP
26 #define SVNXX_EXCEPTION_HPP
27 
28 #include "svn_types_impl.h"
29 
30 #include <exception>
31 #include <memory>
32 #include <new>
33 #include <stdexcept>
34 #include <string>
35 #include <vector>
36 
37 /**
38  * @defgroup svnxx_exceptions SVN++ Exceptions
39  * @brief Exceptions in SVN++
40  *
41  * Exceptions in SVN++
42  * ===================
43  *
44  * SVN++ uses exceptions for the following purposes:
45  * @li Reporting memory allocation failure; where Subversion's
46  * default hehaviour is to abort when an allocation from an APR
47  * pool fails, SVN++ throws an exception instead.
48  * @li Reporting errors; Subversion's error messages are wrapped in
49  * exceptions.
50  * @li Reporting cancelled operations; an operation that was
51  * cancelled from user code will report this by throwing a
52  * specific exception type.
53  * @li Terminating iteration; user-level callbacks may throw a
54  * specific exception type to cancel an ongoing operation that
55  * is generating the callback messages. Other exceptions from
56  * user-level callbacks will be propagated back to the calling
57  * application.
58  *
59  * The SVN++ implementation will also throw standard exceptions when
60  * appropriate. Their use is documented in the relevant modules.
61  *
62  * Exception Hierarchy
63  * -------------------
64  *
65  * All SVN++ exceptions are ultimately derived from @c std::exception.
66  *
67  * * <em>std::exception</em>
68  * + <em>std::bad_alloc</em>
69  * - apache::subversion::svnxx::allocation_failed\n
70  * Thrown when memory cannot be allocated from an APR pool
71  * + <em>std::runtime_error</em>
72  * - apache::subversion::svnxx::error\n
73  * Thrown when an operation failed (see @ref svn_error_t)
74  * - apache::subversion::svnxx::cancelled\n
75  * Thrown when an operation was cancelled, including by the
76  * user code throwing a @c stop_iteration exception (see
77  * below)
78  * + apache::subversion::svnxx::stop_iteration\n
79  * Thrown by user callbacks to terminate iteration
80  *
81  * @{
82  */
83 
84 namespace apache {
85 namespace subversion {
86 namespace svnxx {
87 
88 /**
89  * @brief Exception type that will be thrown when memory allocation fails.
90  */
91 class allocation_failed : public std::bad_alloc
92 {
93 public:
94  virtual ~allocation_failed() noexcept {}
95 
96  virtual const char* what() const noexcept override
97  {
98  return reason;
99  }
100 
101 protected:
102  explicit allocation_failed(const char* what_arg) noexcept
103  : reason(what_arg)
104  {}
105 
106 private:
107  const char* reason;
108 };
109 
110 namespace detail {
111 using error_ptr = std::shared_ptr<svn_error_t>;
112 } // namespace detail
113 
114 /**
115  * Encapsulate a stack of Subversion error codes and messages.
116  */
117 class error : public std::exception,
118  protected detail::error_ptr
119 {
120 public:
121  virtual ~error() {}
122 
123  /**
124  * Returns the message associated with the top-level error that
125  * caused the exception.
126  *
127  * @note the returned string is valid only as long as this @c error
128  * object is in scope.
129  */
130  virtual const char* what() const noexcept override;
131 
132  /**
133  * Returns the error code associated with the top-level error that
134  * caused the exception.
135  */
136  virtual int code() const noexcept;
137 
138  /**
139  * Returns the symbolic name of the error code associated with the
140  * top-level error that caused the exception.
141  * @note The returned value may be @c nullptr.
142  */
143  virtual const char* name() const noexcept;
144 
145  /**
146  * Error message description.
147  */
148  class message
149  {
150  public:
151  /**
152  * Return the error code.
153  */
154  int code() const noexcept { return m_errno; }
155 
156  /**
157  * Return the error name.
158  * @note The returned value may be @c nullptr.
159  */
160  const char* name() const noexcept { return m_errname; }
161 
162  /**
163  * Return the error message.
164  */
165  const std::string& text() const noexcept { return m_message; }
166 
167  /**
168  * Return the generic error message associated with the error code.
169  */
170  std::string generic_text() const;
171 
172  /**
173  * Check if this message is in fact a debugging traceback entry.
174  */
175  bool trace() const noexcept { return m_trace; }
176 
177  protected:
178  message(int errval, const char* errname,
179  const std::string& message_, bool trace)
180  : m_errno(errval),
181  m_errname(errname),
182  m_message(message_),
183  m_trace(trace)
184  {}
185 
186  private:
187  int m_errno;
188  const char* m_errname;
189  std::string m_message;
190  bool m_trace;
191  };
192 
193  /**
194  * Returns the complete list of error messages, including those from
195  * nested errors.
196  */
197  virtual std::vector<message> messages() const
198  {
199  return compile_messages(false);
200  }
201 
202  /**
203  * Like error::messages(), but includes debugging traceback.
204  *
205  * @note
206  * Traceback is only available if the Subversion libraries were
207  * compiled with tracing enabled.
208  */
209  virtual std::vector<message> traced_messages() const
210  {
211  return compile_messages(true);
212  }
213 
214 protected:
215  error(detail::error_ptr err);
216  const char* const m_message;
217  std::vector<message> compile_messages(bool show_traces) const;
218 };
219 
220 /**
221  * Thrown instead of Error when the error chain contains a
222  * @c SVN_ERR_CANCELLED error code.
223  */
224 class cancelled : public error
225 {
226 public:
227  virtual ~cancelled() {}
228 
229 protected:
230  cancelled(detail::error_ptr err)
231  : error(err)
232  {}
233 };
234 
235 /**
236  * User code should throw this exception from callbacks to
237  * cancel an operation.
238  */
239 class stop_iteration : public std::exception
240 {
241 public:
242  stop_iteration() {}
243  virtual ~stop_iteration() {}
244  virtual const char* what() const noexcept override;
245 };
246 
247 } // namespace svnxx
248 } // namespace subversion
249 } // namespace apache
250 
251 /**
252  * @}
253  */
254 #endif // SVNXX_EXCEPTION_HPP
int code() const noexcept
Return the error code.
Definition: exception.hpp:154
Exception type that will be thrown when memory allocation fails.
Definition: exception.hpp:91
Subversion&#39;s data types (common implementation)
virtual std::vector< message > traced_messages() const
Like error::messages(), but includes debugging traceback.
Definition: exception.hpp:209
Thrown instead of Error when the error chain contains a SVN_ERR_CANCELLED error code.
Definition: exception.hpp:224
Encapsulate a stack of Subversion error codes and messages.
Definition: exception.hpp:117
Error message description.
Definition: exception.hpp:148
const char * name() const noexcept
Return the error name.
Definition: exception.hpp:160
User code should throw this exception from callbacks to cancel an operation.
Definition: exception.hpp:239
const std::string & text() const noexcept
Return the error message.
Definition: exception.hpp:165
Definition: depth.hpp:33
bool trace() const noexcept
Check if this message is in fact a debugging traceback entry.
Definition: exception.hpp:175
virtual std::vector< message > messages() const
Returns the complete list of error messages, including those from nested errors.
Definition: exception.hpp:197