source/includes/lv2/lv2_rtmempool.h

   1 /*
   2   LV2 realtime safe memory pool extension definition
   3   This work is in public domain.
   4
   5   This file is distributed in the hope that it will be useful,
   6   but WITHOUT ANY WARRANTY; without even the implied warranty of
   7   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   8
   9   If you have questions, contact Filipe Coelho (aka falkTX) <falktx@falktx.com>
  10   or ask in #lad channel, FreeNode IRC network.
  11 */
  12
  13 /**
  14  * @file lv2_rtmempool.h
  15  * C header for the LV2 rtmempool extension <http://kxstudio.sf.net/ns/lv2ext/rtmempool>.
  16  *
  17  */
  18
  19 #ifndef LV2_RTMEMPOOL_H
  20 #define LV2_RTMEMPOOL_H
  21
  22 #define LV2_RTSAFE_MEMORY_POOL_URI    "http://kxstudio.sf.net/ns/lv2ext/rtmempool"
  23 #define LV2_RTSAFE_MEMORY_POOL_PREFIX LV2_RTSAFE_MEMORY_POOL_URI "#"
  24
  25 #define LV2_RTSAFE_MEMORY_POOL__Pool  LV2_RTSAFE_MEMORY_POOL_URI "Pool"
  26
  27 /** max size of memory pool name, in chars, including terminating zero char */
  28 #define LV2_RTSAFE_MEMORY_POOL_NAME_MAX 128
  29
  30 /** This extension used to be defined by a different URI */
  31 #define LV2_RTSAFE_MEMORY_POOL_DEPRECATED_URI "http://home.gna.org/lv2dynparam/rtmempool/v1"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #else
  36 #include <stdbool.h>
  37 #endif
  38
  39 /**
  40  * Opaque data to host data for LV2_RtMemPool_Pool.
  41  */
  42 typedef void* LV2_RtMemPool_Handle;
  43
  44 /**
  45  * On instantiation, host must supply LV2_RTSAFE_MEMORY_POOL__Pool feature.
  46  * LV2_Feature::data must be pointer to LV2_RtMemPool_Pool.
  47  */
  48 typedef struct _LV2_RtMemPool_Pool {
  49   /**
  50    * This function is called when plugin wants to create memory pool
  51    *
  52    * <b>may/will sleep</b>
  53    *
  54    * @param pool_name pool name, for debug purposes, max RTSAFE_MEMORY_POOL_NAME_MAX chars, including terminating zero char. May be NULL.
  55    * @param data_size memory chunk size
  56    * @param min_preallocated min chunks preallocated
  57    * @param max_preallocated max chunks preallocated
  58    *
  59    * @return Success status, true if successful
  60    */
  61   bool (*create)(LV2_RtMemPool_Handle * handle_ptr,
  62                  const char * pool_name,
  63                  size_t data_size,
  64                  size_t min_preallocated,
  65                  size_t max_preallocated);
  66
  67   /**
  68    * This function is called when plugin wants to destroy previously created memory pool
  69    *
  70    * <b>may/will sleep</b>
  71    */
  72   void (*destroy)(LV2_RtMemPool_Handle handle);
  73
  74   /**
  75    * This function is called when plugin wants to allocate memory in context where sleeping is not allowed
  76    *
  77    * <b>will not sleep</b>
  78    *
  79    * @return Pointer to allocated memory or NULL if memory no memory is available
  80    */
  81   void * (*allocate_atomic)(LV2_RtMemPool_Handle handle);
  82
  83   /**
  84    * This function is called when plugin wants to allocate memory in context where sleeping is allowed
  85    *
  86    * <b>may/will sleep</b>
  87    *
  88    * @return Pointer to allocated memory or NULL if memory no memory is available (should not happen under normal conditions)
  89    */
  90   void * (*allocate_sleepy)(LV2_RtMemPool_Handle handle);
  91
  92   /**
  93    * This function is called when plugin wants to deallocate previously allocated memory
  94    *
  95    * <b>will not sleep</b>
  96    *
  97    * @param memory_ptr pointer to previously allocated memory chunk
  98    */
  99   void (*deallocate)(LV2_RtMemPool_Handle handle,
 100                      void * memory_ptr);
 101
 102 } LV2_RtMemPool_Pool;
 103
 104 /**
 105  * Deprecated feature for backwards compatibility.
 106  */
 107 typedef struct _LV2_RtMemPool_Pool_Deprecated {
 108   unsigned char (*create)(const char*,size_t,size_t,size_t,LV2_RtMemPool_Handle*);
 109   void  (*destroy)(LV2_RtMemPool_Handle);
 110   void* (*allocate_atomic)(LV2_RtMemPool_Handle);
 111   void* (*allocate_sleepy)(LV2_RtMemPool_Handle);
 112   void  (*deallocate)(LV2_RtMemPool_Handle,void*);
 113 } LV2_RtMemPool_Pool_Deprecated;
 114
 115 #ifdef __cplusplus
 116 } /* extern "C" */
 117 #endif
 118
 119 #endif /* LV2_RTMEMPOOL_H */