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        *  Destructs an object of class bad_alloc
 118        *\endenglish
 119        *\german
 120        *  Zerstört ein Objekt der Klasse bad_alloc
 121        *\endgerman */
 122       virtual ~bad_alloc() throw();
 123
 124       virtual const char* what() const throw();
 125   };
 126
 127   /**
 128    *\english
 129    *  18.5.2.2 Type new_handler
 130    *
 131    *  The type of a handler function to be called by operator the new operators
 132    *  when they cannot satisfy a request for additional storage.
 133    *
 134    *  Required behavior: A new_handler shall perform one of the following:
 135    *   - make more storage available for allocation and then return
 136    *   - throw an exception of type bad_alloc or a class derived from bad_alloc
 137    *   - call either abort() or exit()
 138    *\endenglish
 139    *\german
 140    *  18.5.2.2 Typ new_handler
 141    *
 142    *  Der Typ einer Handlerfunktion die von den new-Operatoren aufgerufen wird,
 143    *  wenn dieser eine Speicherallokation nicht erfüllen kann. Der Handler
 144    *  muss eine der folgenden Bedinungen erfüllen:
 145    *   - mehr Speicher zur Verfügung stellen und zur aufrufenden Funktion
 146    *     zurückkehren
 147    *   - eine Ausnahme vom Typ bad_alloc oder einer davon abgeleiteten Klasse
 148    *     werfen
 149    *   - entweder abort() oder exit() aufrufen
 150    *\endgerman */
 151   typedef void (*new_handler)();
 152
 153   /** 18.5.2.3 set_new_handler
 154    *\english
 155    *  Establishes the function designated by new_p as the current new_handler.
 156    *  \param[in] new_p the new new_handler
 157    *  \return 0 on the ﬁrst call, the previous new_handler on subsequent
 158    *          calls.
 159    *\endenglish
 160    *\german
 161    *  Die Funktion new_p wird zum neuen Handler new_handler
 162    *  \param[in] new_p der neue new_handler
 163    *  \return 0 beim ersten Aufruf oder vorhergehender new_handler bei den
 164    *          darauf folgenden Aufrufen
 165    *\endgerman */
 166   new_handler set_new_handler(new_handler new_p) throw();
 167
 168   /*@}*/
 169 }
 170
 171
 172
 173 /** \addtogroup lightlibcpp_18_5_1 */
 174 /*@{*/
 175
 176 /* 18.5.1.1 Single-object forms */
 177
 178 /**
 179  *\english
 180  *  The allocation function called by a new-expression to allocate size bytes
 181  *  suitably aligned to represent any object of that size. If the allocation
 182  *  request cannot be satisfied bad_alloc is thrown (if
 183  *  _LIGHTLIBCPP_NO_EXCEPTIONS is not defined).
 184  *
 185  *  The default behaviour is the following:
 186  *
 187  *  1. call malloc
 188  *
 189  *  2. return the pointer to the allocated space if malloc succeeded
 190  *
 191  *  3. throw bad_alloc if no new_handler is installed
 192  *
 193  *  4. call the new_handler and go to 1
 194  *  \note A C++ program may define a function with this function signature that
 195  *        displaces the default version defined by the C++ Standard library,
 196  *        but the above behaviour is required.
 197  *  \param[in] size number of bytes to allocate
 198  *  \return a pointer to the allocated storage
 199  *\endenglish
 200  *\german
 201  *  Die Allokationsfunktion, die von einem new-Ausdruck aufgerufen wird, um
 202  *  size Bytes mit dem richtigen Alignment für alle Objekte dieser Größe zu
 203  *  allozieren. Falls nicht genügend Speicher vorhanden ist, wird eine
 204  *  Ausnahme vom Typ bad_alloc geworfen (falls _LIGHTLIBCPP_NO_EXCEPTIONS
 205  *  nicht definiert ist).
 206  *
 207  *  Das Standardverhalten ist:
 208  *
 209  *  1. Aufrufen von malloc
 210  *
 211  *  2. den Zeiger auf den allozierten Speicherplatz zurückgeben, falls der
 212  *     malloc-Aufruf erfolgreich war
 213  *
 214  *  3. eine Ausnahme vom Typ bad_alloc werfen, falls kein new_handler
 215  *     installiert ist
 216  *
 217  *  4. den momentan installierten new_handler aufrufen und zu 1 zurückgehen
 218  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 219  *        die die Funktion mit dem Standardverhalten aus der C++
 220  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 221  *        verpflichtend.
 222  *  \param[in] size Anzahl der Bytes die alloziert werden sollen
 223  *  \return ein Zeiger auf den allozierten Speicherplatz
 224  *\endgerman
 225  */
 226 void* operator new(std::size_t size)
 227 #ifndef _LIGHTLIBCPP_NO_EXCEPTIONS
 228    throw(std::bad_alloc);
 229 #else
 230   throw();
 231 #endif
 232
 233 /**
 234  *\english
 235  *  The allocation function called by a placement new-expression to allocate
 236  *  size bytes suitably aligned to represent any object of that size. If the
 237  *  allocation request cannot be satisfied 0 is returned.
 238  *
 239  *  The default behaviour is the following:
 240  *
 241  *  1. call malloc
 242  *
 243  *  2. return the pointer to the allocated space if malloc succeeded
 244  *
 245  *  3. return 0 if no new_handler is installed
 246  *
 247  *  4. call the new_handler and go to 1
 248  *  \note A C++ program may define a function with this function signature that
 249  *        displaces the default version defined by the C++ Standard library,
 250  *        but the above behaviour is required.
 251  *  \param[in] size number of bytes to allocate
 252  *  \return a pointer to the allocated storage or 0
 253  *\endenglish
 254  *\german
 255  *  Die Allokationsfunktion, die von einem placement-new-Ausdruck aufgerufen
 256  *  wird, um size Bytes mit dem richtigen Alignment für alle Objekte dieser
 257  *  Größe zu allozieren. Falls nicht genügend Speicher vorhanden ist, wird 0
 258  *  zurückgegeben.
 259  *
 260  *  Das Standardverhalten ist:
 261  *
 262  *  1. Aufrufen von malloc
 263  *
 264  *  2. den Zeiger auf den allozierten Speicherplatz zurückgeben, falls der
 265  *     malloc-Aufruf erfolgreich war
 266  *
 267  *  3. 0 zurückgeben, falls kein new_handler installiert ist
 268  *
 269  *  4. den momentan installierten new_handler aufrufen und zu 1 zurückgehen
 270  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 271  *        die die Funktion mit dem Standardverhalten aus der C++
 272  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 273  *        verpflichtend.
 274  *  \param[in] size Anzahl der Bytes die alloziert werden sollen
 275  *  \return ein Zeiger auf den allozierten Speicherplatz oder 0
 276  *\endgerman
 277  */
 278 void* operator new(std::size_t size,
 279                    const std::nothrow_t&) throw();
 280
 281 /**
 282  *\english
 283  *  The deallocation function called by a delete-expression to free the memory
 284  *  at the address ptr points to. If ptr is 0, nothing is done.
 285  *
 286  *  ptr must have been allocated with
 287  *
 288  *  * operator new(std::size_t) or with
 289  *
 290  *  * operator new(std::size_t, const std::nothrow_t&)
 291  *  \note A C++ program may define a function with this function signature that
 292  *        displaces the default version defined by the C++ Standard library,
 293  *        but the above behaviour is required.
 294  *  \param[in] ptr the address of the memory supposed to be deallocated
 295  *\endenglish
 296  *\german
 297  *  Die Deallokationsfunktion, welche von einem delete-Ausdruck aufgerufen
 298  *  wird, um den Speicher an der Adresse auf die ptr zeigt freizugeben. Falls
 299  *  ptr 0 ist, wird nichts getan.
 300  *
 301  *  ptr muss mit
 302  *
 303  *  * operator new(std::size_t) oder mit
 304  *
 305  *  * operator new(std::size_t, const std::nothrow_t&)
 306  *
 307  *  alloziert worden sein.
 308  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 309  *        die die Funktion mit dem Standardverhalten aus der C++
 310  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 311  *        verpflichtend.
 312  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 313  *\endgerman
 314  */
 315 void operator delete(void* ptr) throw();
 316
 317 /**
 318  *\english
 319  *  The deallocation function called by a placement delete-expression to free
 320  *  the memory at the address ptr points to. If ptr is 0, nothing is done.
 321  *
 322  *  ptr must have been allocated with
 323  *
 324  *  * operator new(std::size_t) or with
 325  *
 326  *  * operator new(std::size_t, const std::nothrow_t&)
 327  *  \note A C++ program may define a function with this function signature that
 328  *        displaces the default version defined by the C++ Standard library,
 329  *        but the above behaviour is required.
 330  *  \param[in] ptr the address of the memory supposed to be deallocated
 331  *\endenglish
 332  *\german
 333  *  Die Deallokationsfunktion, welche von einem placement-delete-Ausdruck
 334  *  aufgerufen wird, um den Speicher an der Adresse auf die ptr zeigt
 335  *  freizugeben. Falls ptr 0 ist, wird nichts getan.
 336  *
 337  *  ptr muss mit
 338  *
 339  *  * operator new(std::size_t) oder mit
 340  *
 341  *  * operator new(std::size_t, const std::nothrow_t&)
 342  *
 343  *  alloziert worden sein.
 344  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 345  *        die die Funktion mit dem Standardverhalten aus der C++
 346  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 347  *        verpflichtend.
 348  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 349  *\endgerman
 350  */
 351 void operator delete(void* ptr,
 352                      const std::nothrow_t&) throw();
 353
 354
 355
 356 /* 18.5.1.2 Array forms */
 357
 358 /**
 359  *\english
 360  *  The allocation function called by the array form of a new-expression to
 361  *  allocate size bytes suitably aligned to represent any object of that size.
 362  *  If the allocation request cannot be satisfied bad_alloc is thrown (if
 363  *  _LIGHTLIBCPP_NO_EXCEPTIONS is not defined).
 364  *
 365  *  default behaviour: return operator new(size)
 366  *  \note A C++ program may define a function with this function signature that
 367  *        displaces the default version defined by the C++ Standard library,
 368  *        but the above behaviour is required.
 369  *  \param[in] size number of bytes to allocate
 370  *  \return a pointer to the allocated storage
 371  *\endenglish
 372  *\german
 373  *  Die Allokationsfunktion, die von der Array-Version des new-Ausdruck
 374  *  aufgerufen wird, um size Bytes mit dem richtigen Alignment für alle Objekte
 375  *  dieser Größe zu allozieren. Falls nicht genügend Speicher vorhanden ist,
 376  *  wird eine Ausnahme vom Typ bad_alloc geworfen (falls
 377  *  _LIGHTLIBCPP_NO_EXCEPTIONS nicht definiert ist).
 378  *
 379  *  Das Standardverhalten ist: return operator new(size)
 380  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 381  *        die die Funktion mit dem Standardverhalten aus der C++
 382  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 383  *        verpflichtend.
 384  *  \param[in] size Anzahl der Bytes, die alloziert werden sollen
 385  *  \return ein Zeiger auf den allozierten Speicherplatz
 386  *\endgerman
 387  */
 388 void* operator new[](std::size_t size)
 389 #ifndef _LIGHTLIBCPP_NO_EXCEPTIONS
 390   throw(std::bad_alloc);
 391 #else
 392   throw();
 393 #endif
 394
 395 /**
 396  *\english
 397  *  The allocation function called by the array-version of a placement
 398  *  new-expression to allocate size bytes suitably aligned to represent any
 399  *  object of that size. If the allocation request cannot be satisfied 0 is
 400  *  returned.
 401  *
 402  *  The default behaviour is operator new (size, std::nothrow)
 403  *  \note A C++ program may define a function with this function signature that
 404  *        displaces the default version defined by the C++ Standard library,
 405  *        but the above behaviour is required.
 406  *  \param[in] size number of bytes to allocate
 407  *  \return a pointer to the allocated storage or 0
 408  *\endenglish
 409  *\german
 410  *  Die Allokationsfunktion, die von der Array-Version eines
 411  *  placement-new-Ausdruck aufgerufen wird, um size Bytes mit dem richtigen
 412  *  Alignment für alle Objekte dieser Größe zu allozieren. Falls nicht genügend
 413  *  Speicher vorhanden ist, wird 0 zurückgegeben.
 414  *
 415  *  Das Standardverhalten ist: return operator new(size, std::nothrow)
 416  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 417  *        die die Funktion mit dem Standardverhalten aus der C++
 418  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 419  *        verpflichtend.
 420  *  \param[in] size Anzahl der Bytes die alloziert werden sollen
 421  *  \return ein Zeiger auf den allozierten Speicherplatz oder 0
 422  *\endgerman
 423  */
 424 void* operator new[](std::size_t size,
 425                      const std::nothrow_t&) throw();
 426
 427 /**
 428  *\english
 429  *  The deallocation function called by the array-verion of a delete-expression
 430  *  to free the memory at the address ptr points to. If ptr is 0, nothing is
 431  *  done.
 432  *
 433  *  ptr must have been allocated with
 434  *
 435  *  * operator new[](std::size_t) or with
 436  *
 437  *  * operator new[](std::size_t, const std::nothrow_t&)
 438  *  \note A C++ program may define a function with this function signature that
 439  *        displaces the default version defined by the C++ Standard library,
 440  *        but the above behaviour is required.
 441  *  \param[in] ptr the address of the memory supposed to be deallocated
 442  *\endenglish
 443  *\german
 444  *  Die Deallokationsfunktion, welche von der Array-Version eines
 445  *  delete-Ausdrucks aufgerufen wird, um den Speicher an der Adresse auf die
 446  *  ptr zeigt freizugeben. Falls ptr 0 ist, wird nichts getan.
 447  *
 448  *  ptr muss mit
 449  *
 450  *  * operator new[](std::size_t) oder mit
 451  *
 452  *  * operator new[](std::size_t, const std::nothrow_t&)
 453  *
 454  *  alloziert worden sein.
 455  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 456  *        die die Funktion mit dem Standardverhalten aus der C++
 457  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 458  *        verpflichtend.
 459  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 460  *\endgerman
 461  */
 462 void operator delete[](void* ptr) throw();
 463
 464 /**
 465  *\english
 466  *  The deallocation function called by the array-version of a placement
 467  *  delete-expression to free the memory at the address ptr points to. If ptr
 468  *  is 0, nothing is done.
 469  *
 470  *  ptr must have been allocated with
 471  *
 472  *  * operator new[](std::size_t) or with
 473  *
 474  *  * operator new[](std::size_t, const std::nothrow_t&)
 475  *  \note A C++ program may define a function with this function signature that
 476  *        displaces the default version defined by the C++ Standard library,
 477  *        but the above behaviour is required.
 478  *  \param[in] ptr the address of the memory supposed to be deallocated
 479  *\endenglish
 480  *\german
 481  *  Die Deallokationsfunktion, welche von der Array-Version eines
 482  *  placement-delete-Ausdrucks aufgerufen wird, um den Speicher an der Adresse
 483  *  auf die ptr zeigt freizugeben. Falls ptr 0 ist, wird nichts getan.
 484  *
 485  *  ptr muss mit
 486  *
 487  *  * operator new[](std::size_t) oder mit
 488  *
 489  *  * operator new[](std::size_t, const std::nothrow_t&)
 490  *
 491  *  alloziert worden sein.
 492  *  \note Ein C++ Programm darf eine Funktion mit dieser Funktionssignatur,
 493  *        die die Funktion mit dem Standardverhalten aus der C++
 494  *        Standardbibliothek ersetzt, definieren, aber das obige Verhalten ist
 495  *        verpflichtend.
 496  *  \param[in] ptr die Adresse des zu deallozierenden Speichers
 497  *\endgerman
 498  */
 499 void operator delete[](void* ptr,
 500                        const std::nothrow_t&) throw();
 501
 502
 503
 504 /* 18.5.1.3 Placement forms */
 505
 506 /**
 507  *\english
 508  *  Intentionally does nothing
 509  *  \param[in] ptr  returned unchanged
 510  *  \return ptr
 511  *  \note A C++ program may not define a function that displaces this function
 512  *        in the Standard C++ library.
 513  *\endenglish
 514  *\german
 515  *  Tut absichtlich nichts
 516  *  \param[in] ptr  wird unverändert zurückgegeben
 517  *  \return ptr
 518  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 519  *        Funktion der Standard C++ Bibliothek ersetzt.
 520  *\endgerman */
 521 void* operator new(std::size_t,
 522                    void* ptr) throw();
 523
 524 /**
 525  *\english
 526  *  Intentionally does nothing
 527  *  \param[in] ptr  returned unchanged
 528  *  \return ptr
 529  *  \note A C++ program may not define a function that displaces this function
 530  *        in the Standard C++ library.
 531  *\endenglish
 532  *\german
 533  *  Tut absichtlich nichts
 534  *  \param[in] ptr  wird unverändert zurückgegeben
 535  *  \return ptr
 536  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 537  *        Funktion der Standard C++ Bibliothek ersetzt.
 538  *\endgerman */
 539 void* operator new[](std::size_t,
 540                      void* ptr) throw();
 541
 542 /**
 543  *\english
 544  *  Intentionally does nothing
 545  *  \note A C++ program may not define a function that displaces this function
 546  *        in the Standard C++ library.
 547  *\endenglish
 548  *\german
 549  *  Tut absichtlich nichts
 550  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 551  *        Funktion der Standard C++ Bibliothek ersetzt.
 552  *\endgerman */
 553 void operator delete(void*,
 554                      void*) throw();
 555
 556 /**
 557  *\english
 558  *  Intentionally does nothing
 559  *  \note A C++ program may not define a function that displaces this function
 560  *        in the Standard C++ library.
 561  *\endenglish
 562  *\german
 563  *  Tut absichtlich nichts
 564  *  \note Ein C++ Programm darf keine Funktion definieren, welche diese
 565  *        Funktion der Standard C++ Bibliothek ersetzt.
 566  *\endgerman */
 567 void operator delete[](void*,
 568                        void*) throw();
 569
 570 /*@}*/
 571
 572
 573
 574 #endif