[2831] use \throw to describe exceptions where appropriate.

also changed some of `InvalidOperation` cases to
`MemorySegmentError` as it should be basically generic enough at the
base class level.

src/lib/util/memory_segment.h

@@ -129,6 +129,18 @@ public:
     /// use this argument in some implementations to test if all allocated
     /// memory was deallocated properly.
     ///
+    /// Specific implementation may also throw \c MemorySegmentError if it
+    /// encounters violation of implementation specific restrictions.
+    ///
+    /// In general, however, this method must succeed and exception free
+    /// as long as the caller passes valid parameters (\c ptr specifies
+    /// memory previously allocated and \c size is correct).
+    ///
+    /// \throw OutOfRange The passed size doesn't match the allocated memory
+    /// size (when identifiable for the implementation).
+    /// \throw MemorySegmentError Failure of implementation specific
+    /// validation.
+    ///
     /// \param ptr Pointer to the block of memory to free/release. This
     /// should be equal to a value returned by <code>allocate()</code>.
     /// \param size The size of the memory to be freed in bytes. This
@@ -197,6 +209,8 @@ public:
     /// \throw std::bad_alloc Allocation of a segment space for the given name
     /// failed.
     /// \throw InvalidParameter name is NULL.
+    /// \throw MemorySegmentError Failure of implementation specific
+    /// validation.
     ///
     /// \param name A C string to be associated with \c addr. Must not be NULL.
     /// \param addr A memory address returned by a prior call to \c allocate.
@@ -252,6 +266,8 @@ public:
     /// See \c getNamedAddress() about exception consideration.
     ///
     /// \throw InvalidParameter name is NULL.
+    /// \throw MemorySegmentError Failure of implementation specific
+    /// validation.
     ///
     /// \param name A C string of which the segment memory address is to be
     /// deleted. Must not be NULL.

src/lib/util/memory_segment_mapped.cc

@@ -14,6 +14,8 @@
 
 #include <util/memory_segment_mapped.h>
 
+#include <exceptions/exceptions.h>
+
 #include <boost/scoped_ptr.hpp>
 #include <boost/interprocess/exceptions.hpp>
 #include <boost/interprocess/managed_mapped_file.hpp>
@@ -130,7 +132,7 @@ MemorySegmentMapped::~MemorySegmentMapped() {
 void*
 MemorySegmentMapped::allocate(size_t size) {
     if (impl_->read_only_) {
-        isc_throw(InvalidOperation, "allocate attempt on read-only segment");
+        isc_throw(MemorySegmentError, "allocate attempt on read-only segment");
     }
 
     // We explicitly check the free memory size; it appears
@@ -156,7 +158,8 @@ MemorySegmentMapped::allocate(size_t size) {
 void
 MemorySegmentMapped::deallocate(void* ptr, size_t) {
     if (impl_->read_only_) {
-        isc_throw(InvalidOperation, "deallocate attempt on read-only segment");
+        isc_throw(MemorySegmentError,
+                  "deallocate attempt on read-only segment");
     }
 
     // the underlying deallocate() would deal with the case where ptr == NULL,
@@ -186,7 +189,7 @@ MemorySegmentMapped::getNamedAddressImpl(const char* name) {
 bool
 MemorySegmentMapped::setNamedAddressImpl(const char* name, void* addr) {
     if (impl_->read_only_) {
-        isc_throw(InvalidOperation, "setNamedAddress on read-only segment");
+        isc_throw(MemorySegmentError, "setNamedAddress on read-only segment");
     }
 
     if (addr && !impl_->base_sgmt_->belongs_to_segment(addr)) {
@@ -211,7 +214,8 @@ MemorySegmentMapped::setNamedAddressImpl(const char* name, void* addr) {
 bool
 MemorySegmentMapped::clearNamedAddressImpl(const char* name) {
     if (impl_->read_only_) {
-        isc_throw(InvalidOperation, "clearNamedAddress on read-only segment");
+        isc_throw(MemorySegmentError,
+                  "clearNamedAddress on read-only segment");
     }
 
     return (impl_->base_sgmt_->destroy<offset_ptr<void> >(name));
@@ -220,7 +224,7 @@ MemorySegmentMapped::clearNamedAddressImpl(const char* name) {
 void
 MemorySegmentMapped::shrinkToFit() {
     if (impl_->read_only_) {
-        isc_throw(InvalidOperation, "shrinkToFit on read-only segment");
+        isc_throw(MemorySegmentError, "shrinkToFit on read-only segment");
     }
 
     // It appears an assertion failure is triggered within Boost if the size

src/lib/util/memory_segment_mapped.h

@@ -16,7 +16,6 @@
 #define MEMORY_SEGMENT_MAPPED_H
 
 #include <util/memory_segment.h>
-#include <exceptions/exceptions.h>
 
 #include <boost/noncopyable.hpp>
 
@@ -85,8 +84,11 @@ public:
     /// these conditions is not met, \c MemorySegmentOpenError exception
     /// will be thrown.
     ///
+    /// \throw MemorySegmentOpenError see the description.
+    ///
     /// \param filename The file name to be mapped to memory.
-    /// \param create If true and the file does not exist, a new one is created.
+    /// \param create If true and the file does not exist, a new one is
+    /// created.
     /// \param initial_size Specifies the size of the newly created file;
     /// ignored if \c create is false.
     MemorySegmentMapped(const std::string& filename, bool create,
@@ -105,7 +107,7 @@ public:
     /// This version can throw \c MemorySegmentGrown.
     ///
     /// This method cannot be called if the segment object is created in the
-    /// read-only mode; in that case InvalidOperation will be thrown.
+    /// read-only mode; in that case MemorySegmentError will be thrown.
     virtual void* allocate(size_t size);
 
     /// \brief Deallocate/release a segment of memory.
@@ -124,7 +126,7 @@ public:
     /// via \c getNamedAddress().
     ///
     /// This method cannot be called if the segment object is created in the
-    /// read-only mode; in that case InvalidOperation will be thrown.
+    /// read-only mode; in that case MemorySegmentError will be thrown.
     virtual void deallocate(void* ptr, size_t size);
 
     virtual bool allMemoryDeallocated() const;
@@ -138,7 +140,7 @@ public:
     /// version of the method).
     ///
     /// This method cannot be called if the segment object is created in the
-    /// read-only mode; in that case InvalidOperation will be thrown.
+    /// read-only mode; in that case MemorySegmentError will be thrown.
     virtual bool setNamedAddressImpl(const char* name, void* addr);
 
     /// \brief Mapped segment version of getNamedAddress.
@@ -148,7 +150,8 @@ public:
 
     /// \brief Mapped segment version of clearNamedAddress.
     ///
-    /// This version never throws.
+    /// This method cannot be called if the segment object is created in the
+    /// read-only mode; in that case MemorySegmentError will be thrown.
     virtual bool clearNamedAddressImpl(const char* name);
 
     /// \brief Shrink the underlying mapped segment to actually used size.
@@ -168,7 +171,9 @@ public:
     /// segment is not usable anymore.
     ///
     /// This method cannot be called if the segment object is created in the
-    /// read-only mode; in that case InvalidOperation will be thrown.
+    /// read-only mode; in that case MemorySegmentError will be thrown.
+    ///
+    /// \throw MemorySegmentError see the description.
     void shrinkToFit();
 
     /// \brief Return the actual segment size.

src/lib/util/tests/memory_segment_mapped_unittest.cc

@@ -272,19 +272,18 @@ TEST_F(MemorySegmentMappedTest, violateReadOnly) {
     // attempts are prohibited. When detectable it must result in an
     // exception.
     EXPECT_THROW(MemorySegmentMapped(mapped_file).allocate(16),
-                 isc::InvalidOperation);
+                 MemorySegmentError);
     // allocation that would otherwise require growing the segment; permission
     // check should be performed before that.
     EXPECT_THROW(MemorySegmentMapped(mapped_file).
-                 allocate(DEFAULT_INITIAL_SIZE * 2),
-                 isc::InvalidOperation);
+                 allocate(DEFAULT_INITIAL_SIZE * 2), MemorySegmentError);
     EXPECT_THROW(MemorySegmentMapped(mapped_file).setNamedAddress("test",
                                                                   NULL),
-                 isc::InvalidOperation);
+                 MemorySegmentError);
     EXPECT_THROW(MemorySegmentMapped(mapped_file).clearNamedAddress("test"),
-                 isc::InvalidOperation);
+                 MemorySegmentError);
     EXPECT_THROW(MemorySegmentMapped(mapped_file).shrinkToFit(),
-                 isc::InvalidOperation);
+                 MemorySegmentError);
 
     void* ptr = segment_->allocate(sizeof(uint32_t));
     segment_->setNamedAddress("test address", ptr);
@@ -301,7 +300,7 @@ TEST_F(MemorySegmentMappedTest, violateReadOnly) {
     }
 
     EXPECT_THROW(MemorySegmentMapped(mapped_file).deallocate(ptr, 4),
-                 isc::InvalidOperation);
+                 MemorySegmentError);
 }
 
 TEST_F(MemorySegmentMappedTest, getCheckSum) {