nanocoat/include/sjme/closeable.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * A structure instance which can be closed.
  12  *
  13  * @since 2024/08/12
  14  */
  15
  16 #ifndef SQUIRRELJME_CLOSEABLE_H
  17 #define SQUIRRELJME_CLOSEABLE_H
  18
  19 #include "sjme/stdTypes.h"
  20 #include "sjme/atomic.h"
  21 #include "sjme/error.h"
  22 #include "sjme/alloc.h"
  23
  24 /* Anti-C++. */
  25 #ifdef __cplusplus
  26         #ifndef SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_IS_EXTERNED
  28                 #define SJME_CXX_SQUIRRELJME_CLOSEABLE_H
  29 extern "C"
  30 {
  31         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  32 #endif /* #ifdef __cplusplus */
  33
  34 /*--------------------------------------------------------------------------*/
  35
  36 /**
  37  * The closeable base data.
  38  *
  39  * @since 2024/08/12
  40  */
  41 typedef struct sjme_closeableBase sjme_closeableBase;
  42
  43 /**
  44  * The closeable pointer type.
  45  *
  46  * @since 2024/08/12
  47  */
  48 typedef sjme_closeableBase* sjme_closeable;
  49
  50 /** Cast to a closeable. */
  51 #define SJME_AS_CLOSEABLE(x) ((sjme_closeable)(x))
  52
  53 /** Cast to a closeable pointer. */
  54 #define SJME_AS_CLOSEABLEP(x) ((sjme_closeable*)(x))
  55
  56 /**
  57  * This function is called when a closeable has been closed.
  58  *
  59  * @param closeable The current closeable being closed.
  60  * @return Any resultant error, if any.
  61  * @since 2024/08/12
  62  */
  63 typedef sjme_errorCode (*sjme_closeable_closeHandlerFunc)(
  64         sjme_attrInNotNull sjme_closeable closeable);
  65
  66 struct sjme_closeableBase
  67 {
  68         /** Has this been closed? */
  69         sjme_atomic_sjme_jint isClosed;
  70
  71         /** Is this a reference counting closeable? */
  72         sjme_jboolean refCounting;
  73
  74         /** The handler for close. */
  75         sjme_closeable_closeHandlerFunc closeHandler;
  76 };
  77
  78 /**
  79  * Allocates a new closeable.
  80  *
  81  * @param inPool The pool to allocate within.
  82  * @param allocSize The allocation size.
  83  * @param handler The close handler to use.
  84  * @param refCounting Is reference counting used? If not then this is
  85  * a one shot close.
  86  * @param outCloseable The resultant closeable.
  87  * @return On any resultant error, if any.
  88  * @since 2024/09/28
  89  */
  90 sjme_errorCode sjme_closeable_allocR(
  91         sjme_attrInNotNull sjme_alloc_pool* inPool,
  92         sjme_attrInPositiveNonZero sjme_jint allocSize,
  93         sjme_attrInNotNull sjme_closeable_closeHandlerFunc handler,
  94         sjme_attrInValue sjme_jboolean refCounting,
  95         sjme_attrOutNotNull sjme_closeable* outCloseable
  96         SJME_DEBUG_ONLY_COMMA SJME_DEBUG_DECL_FILE_LINE_FUNC_OPTIONAL);
  97
  98 /**
  99  * Allocates a new closeable.
 100  *
 101  * @param inPool The pool to allocate within.
 102  * @param allocSize The allocation size.
 103  * @param handler The close handler to use.
 104  * @param refCounting Is reference counting used? If not then this is
 105  * a one shot close.
 106  * @param outCloseable The resultant closeable.
 107  * @return On any resultant error, if any.
 108  * @since 2024/09/29
 109  */
 110 #define sjme_closeable_alloc(inPool, allocSize, handler, refCounting, \
 111         outCloseable) \
 112         (sjme_closeable_allocR((inPool), (allocSize), (handler), (refCounting), \
 113         (outCloseable) \
 114         SJME_DEBUG_ONLY_COMMA SJME_DEBUG_FILE_LINE_FUNC_OPTIONAL))
 115
 116 /**
 117  * Closes the given closeable and un-references the weak reference.
 118  *
 119  * @param closeable The closeable to close.
 120  * @return Any resultant error, if any.
 121  * @since 2024/08/16
 122  */
 123 sjme_errorCode sjme_closeable_close(
 124         sjme_attrInNotNull sjme_closeable closeable);
 125
 126 /*--------------------------------------------------------------------------*/
 127
 128 /* Anti-C++. */
 129 #ifdef __cplusplus
 130         #ifdef SJME_CXX_SQUIRRELJME_CLOSEABLE_H
 131 }
 132                 #undef SJME_CXX_SQUIRRELJME_CLOSEABLE_H
 133                 #undef SJME_CXX_IS_EXTERNED
 134         #endif /* #ifdef SJME_CXX_SQUIRRELJME_CLOSEABLE_H */
 135 #endif /* #ifdef __cplusplus */
 136
 137 #endif /* SQUIRRELJME_CLOSEABLE_H */