[前][次][番号順一覧][スレッド一覧]

ruby-changes:63853

From: =E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3 <ko1@a...>
Date: Thu, 3 Dec 2020 12:08:16 +0900 (JST)
Subject: [ruby-changes:63853] 84eb2bfab9 (master): include/ruby/internal/xmalloc.h: add doxygen

https://git.ruby-lang.org/ruby.git/commit/?id=84eb2bfab9

From 84eb2bfab940fc9c6962c10ede7f72cee3fb9899 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=8D=9C=E9=83=A8=E6=98=8C=E5=B9=B3?=
 <shyouhei@r...>
Date: Thu, 3 Dec 2020 11:53:56 +0900
Subject: include/ruby/internal/xmalloc.h: add doxygen

Thought it was not a bad idea to document these CAPI. [ci skip]

diff --git a/include/ruby/internal/xmalloc.h b/include/ruby/internal/xmalloc.h
index b0fe863..2de544f 100644
--- a/include/ruby/internal/xmalloc.h
+++ b/include/ruby/internal/xmalloc.h
@@ -54,6 +54,26 @@ RBIMPL_ATTR_NODISCARD() https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/xmalloc.h#L54
 RBIMPL_ATTR_RESTRICT()
 RBIMPL_ATTR_RETURNS_NONNULL()
 RBIMPL_ATTR_ALLOC_SIZE((1))
+/**
+ * Allocates an  object instance.  It is  largely the same as  system malloc(),
+ * except:
+ *
+ *   - It raises Ruby exceptions instead of returning NULL, and
+ *   - In case of `ENOMEM` it tries to GC to make some roon.
+ *
+ * @param[in]  size          Requested amount of memory.
+ * @throw      rb_eMemError  No space left for `size` bytes allocation.
+ * @return     A valid pointer  to an allocated storage instance;  which has at
+ *             least `size` bytes width, with appropriate alignment detected by
+ *             the underlying malloc() routine.
+ * @note       It doesn't return NULL.
+ * @note       Unlike some malloc() implementations, it allocates something and
+ *             returns a meaningful value even when `size` is equl to zero.
+ * @warning    The return  value shall  be invalidated  exactly once  by either
+ *             ruby_xfree(),  ruby_xrealloc(), or  ruby_xrealloc2().   It is  a
+ *             failure to pass it to system free(), because the system and Ruby
+ *             might or might not share the same malloc() implementation.
+ */
 void *ruby_xmalloc(size_t size)
 RBIMPL_ATTR_NOEXCEPT(malloc(size))
 ;
@@ -62,6 +82,29 @@ RBIMPL_ATTR_NODISCARD() https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/xmalloc.h#L82
 RBIMPL_ATTR_RESTRICT()
 RBIMPL_ATTR_RETURNS_NONNULL()
 RBIMPL_ATTR_ALLOC_SIZE((1,2))
+/**
+ * Identical to ruby_xmalloc(), except it allocates `nelems` * `elemsiz` bytes.
+ * This is needed  because the multiplication could integer  overflow.  On such
+ * situations  Ruby does  not try  to  allocate at  all but  raises Ruby  level
+ * exceptions  instead.  If  there  is  no integer  overflow  the behaviour  is
+ * exactly the same as `ruby_xmalloc(nelems*elemsiz)`.
+ *
+ * @param[in]  nelems        Number of elements.
+ * @param[in]  elemsiz       Size of an element.
+ * @throw      rb_eMemError  No space left for allocation.
+ * @throw      rb_eArgError  `nelems` * `elemsiz` would overflow.
+ * @return     A valid pointer  to an allocated storage instance;  which has at
+ *             least  `nelems`  *  `elemsiz`   bytes  width,  with  appropriate
+ *             alignment detected by the underlying malloc() routine.
+ * @note       It doesn't return NULL.
+ * @note       Unlike some malloc() implementations, it allocates something and
+ *             returns a  meaningful value even  when `nelems` or  `elemsiz` or
+ *             both are zero.
+ * @warning    The return  value shall  be invalidated  exactly once  by either
+ *             ruby_xfree(),  ruby_xrealloc(), or  ruby_xrealloc2().   It is  a
+ *             failure to pass it to system free(), because the system and Ruby
+ *             might or might not share the same malloc() implementation.
+ */
 void *ruby_xmalloc2(size_t nelems, size_t elemsiz)
 RBIMPL_ATTR_NOEXCEPT(malloc(nelems * elemsiz))
 ;
@@ -70,6 +113,27 @@ RBIMPL_ATTR_NODISCARD() https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/xmalloc.h#L113
 RBIMPL_ATTR_RESTRICT()
 RBIMPL_ATTR_RETURNS_NONNULL()
 RBIMPL_ATTR_ALLOC_SIZE((1,2))
+/**
+ * Identical  to ruby_xmalloc2(),  except it  zero-fills the  region before  it
+ * returns.  This could also be seen  as a routine identical to ruby_xmalloc(),
+ * except it calls calloc() instead of malloc() internally.
+ *
+ * @param[in]  nelems        Number of elements.
+ * @param[in]  elemsiz       Size of an element.
+ * @throw      rb_eMemError  No space left for allocation.
+ * @throw      rb_eArgError  `nelems` * `elemsiz` would overflow.
+ * @return     A valid pointer  to an allocated storage instance;  which has at
+ *             least  `nelems`  *  `elemsiz`   bytes  width,  with  appropriate
+ *             alignment detected by the underlying calloc() routine.
+ * @note       It doesn't return NULL.
+ * @note       Unlike some calloc() implementations, it allocates something and
+ *             returns a  meaningful value even  when `nelems` or  `elemsiz` or
+ *             both are zero.
+ * @warning    The return  value shall  be invalidated  exactly once  by either
+ *             ruby_xfree(),  ruby_xrealloc(), or  ruby_xrealloc2().   It is  a
+ *             failure to pass it to system free(), because the system and Ruby
+ *             might or might not share the same malloc() implementation.
+ */
 void *ruby_xcalloc(size_t nelems, size_t elemsiz)
 RBIMPL_ATTR_NOEXCEPT(calloc(nelems, elemsiz))
 ;
@@ -77,6 +141,39 @@ RBIMPL_ATTR_NOEXCEPT(calloc(nelems, elemsiz)) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/xmalloc.h#L141
 RBIMPL_ATTR_NODISCARD()
 RBIMPL_ATTR_RETURNS_NONNULL()
 RBIMPL_ATTR_ALLOC_SIZE((2))
+/**
+ * Resize the object instance.
+ *
+ * @param[in]  ptr           A  valid pointer  to an  object instance  that was
+ *                           previously  returned  from either  ruby_xmalloc(),
+ *                           ruby_xmalloc2(),  ruby_xcalloc(), ruby_xrealloc(),
+ *                           or ruby_xrealloc2().
+ * @param[in]  newsiz        Requested new amount of memory.
+ * @throw      rb_eMemError  No space left for `newsiz` bytes allocation.
+ * @retval     ptr           In case  the function  returns the  passed pointer
+ *                           as-is, the object instance  that the pointer holds
+ *                           is  either  grown or  shrunken  to  have at  least
+ *                           `newsiz` bytes.
+ * @retval     otherwise     A  valid  pointer  to  a  newly  allocated  object
+ *                           instance which has at  least `newsiz` bytes width,
+ *                           and  holds previous  contents of  `ptr`.  In  this
+ *                           case `ptr` is  invalidated as if it  was passed to
+ *                           ruby_xfree().
+ * @note       It doesn't return NULL.
+ * @warning    Unlike some realloc() implementations, passing zero to `elemsiz`
+ *             is not the  same as calling ruby_xfree(),  because this function
+ *             never returns NULL.  Something meaningful still returns then.
+ * @warning    It is  a failure not to  check the return value.   Do not assume
+ *             anything on  it.  It could  be either identical to,  or distinct
+ *             form the passed argument.
+ * @warning    Do not  assume anything  on the alignment  of the  return value.
+ *             There is  no guarantee  that it  inherits the  passed argument's
+ *             one.
+ * @warning    The return  value shall  be invalidated  exactly once  by either
+ *             ruby_xfree(),  ruby_xrealloc(), or  ruby_xrealloc2().   It is  a
+ *             failure to pass it to system free(), because the system and Ruby
+ *             might or might not share the same malloc() implementation.
+ */
 void *ruby_xrealloc(void *ptr, size_t newsiz)
 RBIMPL_ATTR_NOEXCEPT(realloc(ptr, newsiz))
 ;
@@ -84,10 +181,73 @@ RBIMPL_ATTR_NOEXCEPT(realloc(ptr, newsiz)) https://github.com/ruby/ruby/blob/trunk/include/ruby/internal/xmalloc.h#L181
 RBIMPL_ATTR_NODISCARD()
 RBIMPL_ATTR_RETURNS_NONNULL()
 RBIMPL_ATTR_ALLOC_SIZE((2,3))
+/**
+ * Identical to ruby_xrealloc(), except it resizes the given object instance to
+ * `newelems`  * `newsiz`  bytes.  This  is needed  because the  multiplication
+ * could integer overflow.   On such situations Ruby does not  try to touch the
+ * contents  of  argument pointer  at  all  but  raises Ruby  level  exceptions
+ * instead.  If there is no integer  overflow the behaviour is exactly the same
+ * as `ruby_xrealloc(ptr,nelems*elemsiz)`.
+ *
+ * This  is   roughly  the  same   as  reallocarray()  function   that  OpenBSD
+ * etc. provides, but also interacts with our GC.
+ *
+ * @param[in]  ptr           A  valid pointer  to an  object instance  that was
+ *                           previously  returned  from either  ruby_xmalloc(),
+ *                           ruby_xmalloc2(),  ruby_xcalloc(), ruby_xrealloc(),
+ *                           or ruby_xrealloc2().
+ * @param[in]  newelems      Requested new number of elements.
+ * @param[in]  newsiz        Requested new size of each element.
+ * @throw      rb_eMemError  No space left for  allocation.
+ * @throw      rb_eArgError  `newelems` * `newsiz` would overflow.
+ * @retval     ptr           In case  the function  returns the  passed pointer
+ *                           as-is, the object instance  that the pointer holds
+ *                           is  either  grown or  shrunken  to  have at  least
+ *                           `newelems` * `newsiz` bytes.
+ * @retval     otherwise     A  valid  pointer  to  a  newly  allocated  object
+ *                           instance which has at  least `newelems` * `newsiz`
+ *                           bytes width, and holds previous contents of `ptr`.
+ *                           In this  case `ptr`  is invalidated  as if  it was
+ *                           passed to ruby_xfree().
+ * @note       It doesn't return NULL.
+ * @warning    Unlike some  realloc() implementations,  passing zero  to either
+ *             `newelems`   or  `elemsiz`   are   not  the   same  as   calling
+ *             ruby_xfree(),   because  this   function  never   returns  NULL.
+ *             Something meaningful still returns then.
+ * @warning    It is  a failu (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]