include/lightlibc++/new.hpp

   1 /*
   2 Permission is granted to use, modify, and / or redistribute at will.
   3
   4 This includes removing authorship notices, re-use of code parts in
   5 other software (with or without giving credit), and / or creating a
   6 commercial product based on it.
   7
   8 This permission is not revocable by the author.
   9
  10 This software is provided as-is. Use it at your own risk. There is
  11 no warranty whatsoever, neither expressed nor implied, and by using
  12 this software you accept that the author(s) shall not be held liable
  13 for any loss of data, loss of service, or other damages, be they
  14 incidental or consequential. Your only option other than accepting
  15 this is not to use the software at all.
  16 */
  17 #ifndef _LIGHTLIBCPP_NEW_HPP
  18 #define _LIGHTLIBCPP_NEW_HPP
  19
  20
  21
  22 #include <cstddef>           // std::size_t
  23 #include <exception>         // std::exception
  24
  25
  26
  27 namespace std
  28 {
  29   /* (Forward) declaration of std::bad_alloc */
  30   class bad_alloc;
  31
  32
  33
  34   /** \addtogroup lightlibcpp_18_5 */
  35   /*@{*/
  36
  37   /**
  38    *\english
  39    *  \brief Support structure for nothrow-new operator
  40    *
  41    *  Support structure for the usage of the nothrow-new operator. This
  42    *  structure is intentionally empty.
  43    *\endenglish
  44    *\german
  45    *  \brief Struktur zur Unterstützung des nothrow-new Operators
  46    *
  47    *  Die Struktur ermöglicht das Benutzen des nothrow-new Operators und ist
  48    *  absichtlich leer.
  49    *\endgerman */
  50   struct nothrow_t
  51   {
  52   };
  53
  54   /**
  55    *\english
  56    *  External instance of the nothrow_t structure.
  57    *\endenglish
  58    *\german
  59    *  Externe Instanz der nothrow_t-Struktur.
  60    *\endgerman */
  61   extern const nothrow_t nothrow;
  62
  63   /*@}*/
  64
  65
  66
  67   /** \addtogroup lightlibcpp_18_5_2 */
  68   /*@{*/
  69
  70   /**
  71    *\english
  72    *  \brief Exception to report failure to allocate storage
  73    *
  74    *  18.5.2.1 Class bad_alloc
  75    *
  76    *  The class bad_alloc deﬁnes the type of objects thrown as exceptions by
  77    *  the implementation to report a failure to allocate storage.
  78    *\endenglish
  79    *\german
  80    *  \brief Ausnahme um Fehlschlag einer Speicherallokation anzuzeigen
  81    *
  82    *  18.5.2.1 Klasse bad_alloc
  83    *
  84    *  Die Klasse bad_alloc definiert den Objekttyp, welcher als Ausnahme
  85    *  geworfen wird, um den Fehlschlag einer Speicherallokation anzuzeigen.
  86    *\endgerman */
  87   class bad_alloc : public std::exception
  88   {
  89     public:
  90       /**
  91        *\english
  92        *  Constructs an object of class bad_alloc.
  93        *\endenglish
  94        *\german
  95        *  Konstruiert ein Objekt der Klasse bad_alloc.
  96        *\endgerman */
  97       inline bad_alloc() throw()
  98       {
  99       }
 100
 101       /**
 102        *\english
 103        *  Copies an object of class bad_alloc.
 104        *  \param[in] x reference to the object to copy
 105        *\endenglish
 106        *\german
 107        *  Kopiert ein Objekt der Klasse bad_alloc.
 108        *  \param[in] x Referenz auf das zu kopierende Objekt
 109        *\endgerman */
 110       inline bad_alloc(const bad_alloc& x) throw()
 111         : std::exception(x)
 112       {
 113       }
 114
 115       /**
 116        *\english
 117        *  Copies an object of class bad_alloc.
 118        *  \param[in] x reference to the object to copy
 119        *\endenglish
 120        *\german
 121        *  Kopiert ein Objekt der Klasse bad_alloc.
 122        *  \param[in] x Referenz auf das zu kopierende Objekt
 123        *\endgerman */
 124       inline bad_alloc& operator = (const bad_alloc& x) throw()
 125       {
 126         (void)x;
 127         return *this;
 128       }
 129
 130       /**
 131        *\english
 132        *  Destructs an object of class bad_alloc
 133        *\endenglish
 134        *\german
 135        *  Zerstört ein Objekt der Klasse bad_alloc
 136        *\endgerman */
 137       virtual ~bad_alloc() throw();
 138
 139       virtual const char* what() const throw();
 140   };
 141
 142   /**
 143    *\english
 144    *  18.5.2.2 Type new_handler
 145    *
 146    *  The type of a handler function to be called by operator the new operators
 147    *  when they cannot satisfy a request for additional storage.
 148    *
 149    *  Required behavior: A new_handler shall perform one of the following:
 150    *   - make more storage available for allocation and then return
 151    *   - throw an exception of type bad_alloc or a class derived from bad_alloc
 152    *   - call either abort() or exit()
 153    *\endenglish
 154    *\german
 155    *  18.5.2.2 Typ new_handler
 156    *
 157    *  Der Typ einer Handlerfunktion die von den new-Operatoren aufgerufen wird,
 158    *  wenn dieser eine Speicherallokation nicht erfüllen kann. Der Handler
 159    *  muss eine der folgenden Bedinungen erfüllen:
 160    *   - mehr Speicher zur Verfügung stellen und zur aufrufenden Funktion
 161    *     zurückkehren
 162    *   - eine Ausnahme vom Typ bad_alloc oder einer davon abgeleiteten Klasse
 163    *     werfen
 164    *   - entweder abort() oder exit() aufrufen
 165    *\endgerman */
 166   typedef void (*new_handler)();
 167
 168   /** 18.5.2.3 set_new_handler
 169    *\english
 170    *  Establishes the function designated by new_p as the current new_handler.
 171    *  \param[in] new_p the new new_handler
 172    *  \return 0 on the ﬁrst call, the previous new_handler on subsequent
 173    *          calls.
 174    *\endenglish
 175    *\german
 176    *  Die Funktion new_p wird zum neuen Handler new_handler
 177    *  \param[in] new_p der neue new_handler
 178    *  \return 0 beim ersten Aufruf oder vorhergehender new_handler bei den
 179    *          darauf folgenden Aufrufen
 180    *\endgerman */
 181   new_handler set_new_handler(new_handler new_p) throw();
 182
 183   /*@}*/
 184 }
 185
 186
 187
 188 /** \addtogroup lightlibcpp_18_5_1 */
 189 /*@{*/
 190
 191 /* 18.5.1.1 Single-object forms */
 192
 193 /**
 194  *\english
 195  *  The allocation function called by a new-expression to allocate size bytes
 196  *  suitably aligned to represent any object of that size. If the allocation
 197  *  request cannot be satisfied bad_alloc is thrown (if
 198  *  _LIGHTLIBCPP_NO_EXCEPTIONS is not defined).
 199  *
 200  *  The default behaviour is the following:
 201  *
 202  *  1. call malloc
 203  *
 204  *  2. return the pointer to the allocated space if malloc succeeded
 205  *
 206  *  3. throw bad_alloc if no new_handler is installed
 207  *
 208  *  4. call the new_handler and go to 1
 209  *  \note A C++ program may define a function with this function signature that
 210  *        displaces the default version defined by the C++ Standard library,
 211  *        but the above behaviour is required.
 212  *  \param[in] size number of bytes to allocate
 213  *  \return a pointer to the allocated storage
 214  *\endenglish
 215  *\german
 216  *  Die Allokationsfunktion, die von einem new-Ausdruck aufgerufen wird, um
 217  *  size Bytes mit dem richtigen Alignment für alle Objekte dieser Größe zu
 218  *  allozieren. Falls nicht genügend Speicher vorhanden ist, wird eine
 219  *  Ausnahme vom Typ bad_alloc geworfen (falls _LIGHTLIBCPP_NO_EXCEPTIONS
 220  *  nicht definiert ist).
 221  *
 222  *  Das Standardverhalten ist:
 223  *
 224  *  1. Aufrufen von malloc
 225  *
 226  *  2. den Zeiger auf den allozierten Speicherplatz zurückgeben, falls der
 227  *     malloc-Aufruf erfolgreich war
 228  *
 229  *  3. eine Ausnahme vom Typ bad_alloc werfen, falls kein new_handler
 230  *     installiert ist
 231  *
 232  *  4. den momentan installierten new_handler aufrufen und zu 1 zurückgehen
 233  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 234  *        die die Funktion mit dem Standardverhalten aus der C++
 235  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 236  *        verpflichtend.
 237  *  \param[in] size Anzahl der Bytes die alloziert werden sollen
 238  *  \return ein Zeiger auf den allozierten Speicherplatz
 239  *\endgerman
 240  */
 241 void* operator new(std::size_t size)
 242 #ifndef _LIGHTLIBCPP_NO_EXCEPTIONS
 243    throw(std::bad_alloc);
 244 #else
 245   throw();
 246 #endif
 247
 248 /**
 249  *\english
 250  *  The allocation function called by a placement new-expression to allocate
 251  *  size bytes suitably aligned to represent any object of that size. If the
 252  *  allocation request cannot be satisfied 0 is returned.
 253  *
 254  *  The default behaviour is the following:
 255  *
 256  *  1. call malloc
 257  *
 258  *  2. return the pointer to the allocated space if malloc succeeded
 259  *
 260  *  3. return 0 if no new_handler is installed
 261  *
 262  *  4. call the new_handler and go to 1
 263  *  \note A C++ program may define a function with this function signature that
 264  *        displaces the default version defined by the C++ Standard library,
 265  *        but the above behaviour is required.
 266  *  \param[in] size number of bytes to allocate
 267  *  \return a pointer to the allocated storage or 0
 268  *\endenglish
 269  *\german
 270  *  Die Allokationsfunktion, die von einem placement-new-Ausdruck aufgerufen
 271  *  wird, um size Bytes mit dem richtigen Alignment für alle Objekte dieser
 272  *  Größe zu allozieren. Falls nicht genügend Speicher vorhanden ist, wird 0
 273  *  zurückgegeben.
 274  *
 275  *  Das Standardverhalten ist:
 276  *
 277  *  1. Aufrufen von malloc
 278  *
 279  *  2. den Zeiger auf den allozierten Speicherplatz zurückgeben, falls der
 280  *     malloc-Aufruf erfolgreich war
 281  *
 282  *  3. 0 zurückgeben, falls kein new_handler installiert ist
 283  *
 284  *  4. den momentan installierten new_handler aufrufen und zu 1 zurückgehen
 285  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 286  *        die die Funktion mit dem Standardverhalten aus der C++
 287  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 288  *        verpflichtend.
 289  *  \param[in] size Anzahl der Bytes die alloziert werden sollen
 290  *  \return ein Zeiger auf den allozierten Speicherplatz oder 0
 291  *\endgerman
 292  */
 293 void* operator new(std::size_t size,
 294                    const std::nothrow_t&) throw();
 295
 296 /**
 297  *\english
 298  *  The deallocation function called by a delete-expression to free the memory
 299  *  at the address ptr points to. If ptr is 0, nothing is done.
 300  *
 301  *  ptr must have been allocated with
 302  *
 303  *  * operator new(std::size_t) or with
 304  *
 305  *  * operator new(std::size_t, const std::nothrow_t&)
 306  *  \note A C++ program may define a function with this function signature that
 307  *        displaces the default version defined by the C++ Standard library,
 308  *        but the above behaviour is required.
 309  *  \param[in] ptr the address of the memory supposed to be deallocated
 310  *\endenglish
 311  *\german
 312  *  Die Deallokationsfunktion, welche von einem delete-Ausdruck aufgerufen
 313  *  wird, um den Speicher an der Adresse auf die ptr zeigt freizugeben. Falls
 314  *  ptr 0 ist, wird nichts getan.
 315  *
 316  *  ptr muss mit
 317  *
 318  *  * operator new(std::size_t) oder mit
 319  *
 320  *  * operator new(std::size_t, const std::nothrow_t&)
 321  *
 322  *  alloziert worden sein.
 323  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 324  *        die die Funktion mit dem Standardverhalten aus der C++
 325  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 326  *        verpflichtend.
 327  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 328  *\endgerman
 329  */
 330 void operator delete(void* ptr) throw();
 331
 332 /**
 333  *\english
 334  *  The deallocation function called by a placement delete-expression to free
 335  *  the memory at the address ptr points to. If ptr is 0, nothing is done.
 336  *
 337  *  ptr must have been allocated with
 338  *
 339  *  * operator new(std::size_t) or with
 340  *
 341  *  * operator new(std::size_t, const std::nothrow_t&)
 342  *  \note A C++ program may define a function with this function signature that
 343  *        displaces the default version defined by the C++ Standard library,
 344  *        but the above behaviour is required.
 345  *  \param[in] ptr the address of the memory supposed to be deallocated
 346  *\endenglish
 347  *\german
 348  *  Die Deallokationsfunktion, welche von einem placement-delete-Ausdruck
 349  *  aufgerufen wird, um den Speicher an der Adresse auf die ptr zeigt
 350  *  freizugeben. Falls ptr 0 ist, wird nichts getan.
 351  *
 352  *  ptr muss mit
 353  *
 354  *  * operator new(std::size_t) oder mit
 355  *
 356  *  * operator new(std::size_t, const std::nothrow_t&)
 357  *
 358  *  alloziert worden sein.
 359  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 360  *        die die Funktion mit dem Standardverhalten aus der C++
 361  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 362  *        verpflichtend.
 363  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 364  *\endgerman
 365  */
 366 void operator delete(void* ptr,
 367                      const std::nothrow_t&) throw();
 368
 369
 370
 371 /* 18.5.1.2 Array forms */
 372
 373 /**
 374  *\english
 375  *  The allocation function called by the array form of a new-expression to
 376  *  allocate size bytes suitably aligned to represent any object of that size.
 377  *  If the allocation request cannot be satisfied bad_alloc is thrown (if
 378  *  _LIGHTLIBCPP_NO_EXCEPTIONS is not defined).
 379  *
 380  *  default behaviour: return operator new(size)
 381  *  \note A C++ program may define a function with this function signature that
 382  *        displaces the default version defined by the C++ Standard library,
 383  *        but the above behaviour is required.
 384  *  \param[in] size number of bytes to allocate
 385  *  \return a pointer to the allocated storage
 386  *\endenglish
 387  *\german
 388  *  Die Allokationsfunktion, die von der Array-Version des new-Ausdruck
 389  *  aufgerufen wird, um size Bytes mit dem richtigen Alignment für alle Objekte
 390  *  dieser Größe zu allozieren. Falls nicht genügend Speicher vorhanden ist,
 391  *  wird eine Ausnahme vom Typ bad_alloc geworfen (falls
 392  *  _LIGHTLIBCPP_NO_EXCEPTIONS nicht definiert ist).
 393  *
 394  *  Das Standardverhalten ist: return operator new(size)
 395  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 396  *        die die Funktion mit dem Standardverhalten aus der C++
 397  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 398  *        verpflichtend.
 399  *  \param[in] size Anzahl der Bytes, die alloziert werden sollen
 400  *  \return ein Zeiger auf den allozierten Speicherplatz
 401  *\endgerman
 402  */
 403 void* operator new[](std::size_t size)
 404 #ifndef _LIGHTLIBCPP_NO_EXCEPTIONS
 405   throw(std::bad_alloc);
 406 #else
 407   throw();
 408 #endif
 409
 410 /**
 411  *\english
 412  *  The allocation function called by the array-version of a placement
 413  *  new-expression to allocate size bytes suitably aligned to represent any
 414  *  object of that size. If the allocation request cannot be satisfied 0 is
 415  *  returned.
 416  *
 417  *  The default behaviour is operator new (size, std::nothrow)
 418  *  \note A C++ program may define a function with this function signature that
 419  *        displaces the default version defined by the C++ Standard library,
 420  *        but the above behaviour is required.
 421  *  \param[in] size number of bytes to allocate
 422  *  \return a pointer to the allocated storage or 0
 423  *\endenglish
 424  *\german
 425  *  Die Allokationsfunktion, die von der Array-Version eines
 426  *  placement-new-Ausdruck aufgerufen wird, um size Bytes mit dem richtigen
 427  *  Alignment für alle Objekte dieser Größe zu allozieren. Falls nicht genügend
 428  *  Speicher vorhanden ist, wird 0 zurückgegeben.
 429  *
 430  *  Das Standardverhalten ist: return operator new(size, std::nothrow)
 431  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 432  *        die die Funktion mit dem Standardverhalten aus der C++
 433  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 434  *        verpflichtend.
 435  *  \param[in] size Anzahl der Bytes die alloziert werden sollen
 436  *  \return ein Zeiger auf den allozierten Speicherplatz oder 0
 437  *\endgerman
 438  */
 439 void* operator new[](std::size_t size,
 440                      const std::nothrow_t&) throw();
 441
 442 /**
 443  *\english
 444  *  The deallocation function called by the array-verion of a delete-expression
 445  *  to free the memory at the address ptr points to. If ptr is 0, nothing is
 446  *  done.
 447  *
 448  *  ptr must have been allocated with
 449  *
 450  *  * operator new[](std::size_t) or with
 451  *
 452  *  * operator new[](std::size_t, const std::nothrow_t&)
 453  *  \note A C++ program may define a function with this function signature that
 454  *        displaces the default version defined by the C++ Standard library,
 455  *        but the above behaviour is required.
 456  *  \param[in] ptr the address of the memory supposed to be deallocated
 457  *\endenglish
 458  *\german
 459  *  Die Deallokationsfunktion, welche von der Array-Version eines
 460  *  delete-Ausdrucks aufgerufen wird, um den Speicher an der Adresse auf die
 461  *  ptr zeigt freizugeben. Falls ptr 0 ist, wird nichts getan.
 462  *
 463  *  ptr muss mit
 464  *
 465  *  * operator new[](std::size_t) oder mit
 466  *
 467  *  * operator new[](std::size_t, const std::nothrow_t&)
 468  *
 469  *  alloziert worden sein.
 470  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 471  *        die die Funktion mit dem Standardverhalten aus der C++
 472  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 473  *        verpflichtend.
 474  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 475  *\endgerman
 476  */
 477 void operator delete[](void* ptr) throw();
 478
 479 /**
 480  *\english
 481  *  The deallocation function called by the array-version of a placement
 482  *  delete-expression to free the memory at the address ptr points to. If ptr
 483  *  is 0, nothing is done.
 484  *
 485  *  ptr must have been allocated with
 486  *
 487  *  * operator new[](std::size_t) or with
 488  *
 489  *  * operator new[](std::size_t, const std::nothrow_t&)
 490  *  \note A C++ program may define a function with this function signature that
 491  *        displaces the default version defined by the C++ Standard library,
 492  *        but the above behaviour is required.
 493  *  \param[in] ptr the address of the memory supposed to be deallocated
 494  *\endenglish
 495  *\german
 496  *  Die Deallokationsfunktion, welche von der Array-Version eines
 497  *  placement-delete-Ausdrucks aufgerufen wird, um den Speicher an der Adresse
 498  *  auf die ptr zeigt freizugeben. Falls ptr 0 ist, wird nichts getan.
 499  *
 500  *  ptr muss mit
 501  *
 502  *  * operator new[](std::size_t) oder mit
 503  *
 504  *  * operator new[](std::size_t, const std::nothrow_t&)
 505  *
 506  *  alloziert worden sein.
 507  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 508  *        die die Funktion mit dem Standardverhalten aus der C++
 509  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 510  *        verpflichtend.
 511  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 512  *\endgerman
 513  */
 514 void operator delete[](void* ptr,
 515                        const std::nothrow_t&) throw();
 516
 517
 518
 519 /* 18.5.1.3 Placement forms */
 520
 521 /**
 522  *\english
 523  *  Intentionally does nothing
 524  *  \param[in] ptr  returned unchanged
 525  *  \return ptr
 526  *  \note A C++ program may not define a function that displaces this function
 527  *        in the Standard C++ library.
 528  *\endenglish
 529  *\german
 530  *  Tut absichtlich nichts
 531  *  \param[in] ptr  wird unverändert zurückgegeben
 532  *  \return ptr
 533  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 534  *        Funktion der Standard C++ Bibliothek ersetzt.
 535  *\endgerman */
 536 void* operator new(std::size_t,
 537                    void* ptr) throw();
 538
 539 /**
 540  *\english
 541  *  Intentionally does nothing
 542  *  \param[in] ptr  returned unchanged
 543  *  \return ptr
 544  *  \note A C++ program may not define a function that displaces this function
 545  *        in the Standard C++ library.
 546  *\endenglish
 547  *\german
 548  *  Tut absichtlich nichts
 549  *  \param[in] ptr  wird unverändert zurückgegeben
 550  *  \return ptr
 551  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 552  *        Funktion der Standard C++ Bibliothek ersetzt.
 553  *\endgerman */
 554 void* operator new[](std::size_t,
 555                      void* ptr) throw();
 556
 557 /**
 558  *\english
 559  *  Intentionally does nothing
 560  *  \note A C++ program may not define a function that displaces this function
 561  *        in the Standard C++ library.
 562  *\endenglish
 563  *\german
 564  *  Tut absichtlich nichts
 565  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 566  *        Funktion der Standard C++ Bibliothek ersetzt.
 567  *\endgerman */
 568 void operator delete(void*,
 569                      void*) throw();
 570
 571 /**
 572  *\english
 573  *  Intentionally does nothing
 574  *  \note A C++ program may not define a function that displaces this function
 575  *        in the Standard C++ library.
 576  *\endenglish
 577  *\german
 578  *  Tut absichtlich nichts
 579  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 580  *        Funktion der Standard C++ Bibliothek ersetzt.
 581  *\endgerman */
 582 void operator delete[](void*,
 583                        void*) throw();
 584
 585 /*@}*/
 586
 587
 588
 589 #endif