version: "0.4.2"
classes:
  - name: "MemoryManager"
    doc: "Container for memory management functions in Stumpless."
    namespace: "stumpless"
    equivalent-struct:
      # this is a dummy struct simply to get wrapture to work
      name: "stumpless_version"
      includes: "stumpless/version.h"
    functions:
      - name: "FreeAll"
        doc: |
          Frees all memory allocated internally, and performs any other
          necessary cleanup.

          This function serves as a final exit function, which should be called
          when an application using the library is preparing to exit or when the
          library is no longer needed. Before this function is called, all
          targets must be closed and no pointers to any structs should be
          retained. Failing to do this will result in undefined behavior.

          Calling other functions after a call to this function is acceptable,
          however execution times may be longer than usual as memory used to
          cache objects may need to be allocated again. If other functions are
          called, this function should be called again before exit to ensure a
          memory leak does not exist.

          In a windows environment, this function will call WSACleanup as part
          of its cleanup.
        static: true
        wrapped-function:
          name: "stumpless_free_all"
          includes: "stumpless/memory.h"
      - name: "FreeThread"
        doc: |
          Frees all memory allocated internally to the calling thread, and
          performs any other thread-specific cleanup.

          This function should be called in any thread that has used stumpless
          functions before it exits so that caches and other structures can be
          cleaned up. It is not a substitute for stumpless_free_all, but is
          called by it and can be left out if stumpless_free_all will be called
          later in the same thread.

          Available since release v2.0.0.
        static: true
        wrapped-function:
          name: "stumpless_free_thread"
          includes: "stumpless/memory.h"
      - name: "SetMalloc"
        doc: "Sets the function used by Stumpless to allocate memory."
        static: true
        params:
          - name: "malloc_func"
            doc: >
              A pointer to the allocation function that is desired. This
              function must have the same signature as the standard library
              malloc function, which is the default allocation function.
            type:
              function:
                params:
                  - type:
                      name: "size_t"
                      includes: "stddef.h"
                return:
                  type: "void *"
        return:
          doc: "The new allocation function."
          type:
            function:
              params:
                - type:
                    name: "size_t"
                    includes: "stddef.h"
              return:
                type: "void *"
        wrapped-function:
          name: "stumpless_set_malloc"
          includes: "stumpless/memory.h"
          params:
            - value: "malloc_func"
      - name: "SetFree"
        doc: "Sets the function used by Stumpless to free memory."
        static: true
        params:
          - name: "free_func"
            doc: >
              A pointer to the memory deallocation function that is desired.
              This function must have the same signature as the standard library
              free function, which is the default deallocation function.
            type:
              function:
                params:
                  - type: "void *"
                return:
                  type: "void"
        return:
          doc: "The new deallocation function."
          type:
            function:
              params:
                - type: "void *"
              return:
                type: "void"
        wrapped-function:
          name: "stumpless_set_free"
          includes: "stumpless/memory.h"
          params:
            - value: "free_func"
      - name: "SetRealloc"
        doc: "Sets the function used by Stumpless to reallocate memory."
        static: true
        params:
          - name: "realloc_func"
            doc: >
              A pointer to the memory reallocation function that is desired.
              This function must have the same signature as the standard library
              realloc function, which is the default reallocation function.
            type:
              function:
                params:
                  - type: "void *"
                  - type:
                      name: "size_t"
                      includes: "stddef.h"
                return:
                  type: "void *"
        return:
          doc: "The new reallocation function."
          type:
            function:
              params:
                - type: "void *"
                - type:
                    name: "size_t"
                    includes: "stddef.h"
              return:
                type: "void *"
        wrapped-function:
          name: "stumpless_set_realloc"
          includes: "stumpless/memory.h"
          params:
            - value: "realloc_func"