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