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 /**
  54  * This function is called when a closeable has been closed.
  55  *
  56  * @param closeable The current closeable being closed.
  57  * @return Any resultant error, if any.
  58  * @since 2024/08/12
  59  */
  60 typedef sjme_errorCode (*sjme_closeable_closeHandlerFunc)(
  61         sjme_attrInNotNull sjme_closeable closeable);
  62
  63 struct sjme_closeableBase
  64 {
  65         /** Has this been closed? */
  66         sjme_atomic_sjme_jint isClosed;
  67
  68         /** Is this a reference counting closeable? */
  69         sjme_jboolean refCounting;
  70
  71         /** The handler for close. */
  72         sjme_closeable_closeHandlerFunc closeHandler;
  73 };
  74
  75 /**
  76  * This is a method that can be used for weak reference enqueue which will
  77  * call the close method.
  78  *
  79  * @param weak The weak reference being destroyed.
  80  * @param data The data to pass.
  81  * @param isBlockFree Is this from a block free?
  82  * @return Any resultant error, if any.
  83  * @since 2024/08/12
  84  */
  85 sjme_errorCode sjme_closeable_autoEnqueue(
  86         sjme_attrInNotNull sjme_alloc_weak weak,
  87         sjme_attrInNullable sjme_pointer data,
  88         sjme_attrInValue sjme_jboolean isBlockFree);
  89
  90 /**
  91  * Closes the given closeable.
  92  *
  93  * @param closeable The closeable to close.
  94  * @return Any resultant error, if any.
  95  * @since 2024/08/11
  96  */
  97 sjme_errorCode sjme_closeable_closeNoUnRef(
  98         sjme_attrInNotNull sjme_closeable closeable);
  99
 100 /**
 101  * Closes the given closeable and un-references the weak reference.
 102  *
 103  * @param closeable The closeable to close.
 104  * @return Any resultant error, if any.
 105  * @since 2024/08/16
 106  */
 107 sjme_errorCode sjme_closeable_close(
 108         sjme_attrInNotNull sjme_closeable closeable);
 109
 110 /*--------------------------------------------------------------------------*/
 111
 112 /* Anti-C++. */
 113 #ifdef __cplusplus
 114         #ifdef SJME_CXX_SQUIRRELJME_CLOSEABLE_H
 115 }
 116                 #undef SJME_CXX_SQUIRRELJME_CLOSEABLE_H
 117                 #undef SJME_CXX_IS_EXTERNED
 118         #endif /* #ifdef SJME_CXX_SQUIRRELJME_CLOSEABLE_H */
 119 #endif /* #ifdef __cplusplus */
 120
 121 #endif /* SQUIRRELJME_CLOSEABLE_H */