nanocoat/include/sjme/frontEnd.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  * Front end bindings.
  12  *
  13  * @since 2024/09/04
  14  */
  15
  16 #ifndef SQUIRRELJME_FRONTEND_H
  17 #define SQUIRRELJME_FRONTEND_H
  18
  19 #include "sjme/stdTypes.h"
  20 #include "sjme/error.h"
  21 #include "sjme/multithread.h"
  22
  23 /* Anti-C++. */
  24 #ifdef __cplusplus
  25         #ifndef SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_IS_EXTERNED
  27                 #define SJME_CXX_SQUIRRELJME_FRONTEND_H
  28 extern "C"
  29 {
  30         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  31 #endif /* #ifdef __cplusplus */
  32
  33 /*--------------------------------------------------------------------------*/
  34
  35 /**
  36  * A wrapper used by front ends, which is reserved for use, which stores a
  37  * natively bound object accordingly as needed.
  38  *
  39  * @since 2023/12/06
  40  */
  41 typedef sjme_pointer sjme_frontEndWrapper;
  42
  43 /**
  44  * Any data that is needed by the front end, which is reserved for use.
  45  *
  46  * @since 2023/12/14
  47  */
  48 typedef sjme_pointer sjme_frontEndData;
  49
  50 /**
  51  * The action to perform when binding.
  52  *
  53  * @since 2024/09/04
  54  */
  55 typedef enum sjme_frontEnd_bindAction
  56 {
  57         /** Obtain the binding. */
  58         SJME_FRONTEND_BIND,
  59
  60         /** Release the binding. */
  61         SJME_FRONTEND_RELEASE,
  62
  63         /** The number of actions. */
  64         SJME_FRONTEND_NUM_BIND_ACTION,
  65 } sjme_frontEnd_bindAction;
  66
  67 /**
  68  * The type of binding this is.
  69  *
  70  * @since 2024/09/04
  71  */
  72 typedef enum sjme_frontEnd_bindType
  73 {
  74         /**
  75          * Strong reference to the binding, this means that the data referred
  76          * to by the front end will not disappear.
  77          *
  78          * An example of a strong reference would be a Java callback that needs
  79          * both it's own object along with the native structure to always exist.
  80          */
  81         SJME_FRONTEND_STRONG,
  82
  83         /**
  84          * Weak reference to the binding, this means that the data referred to
  85          * by the front end may disappear in the front end, for example if
  86          * the front end has a garbage collection scheme.
  87          *
  88          * An example of a weak reference would be a ScritchUI type that needs
  89          * access from a garbage collected virtual machine, such as the
  90          * emulator/standalone variant of SquirrelJME, in that the object this
  91          * points to only exists to point back to a native structure. To continue
  92          * the graphics example, a PencilBracket only needs to exist during
  93          * drawing and once that gets garbage collected the native structure can
  94          * be freed if nothing else refers to it. If a context is reused after
  95          * the Java object was garbage collected, then that reference object
  96          * will just be recreated to point to the native structure. Only once
  97          * the native structure is no longer needed AND the Java object is garbage
  98          * collected, then the native structure may be freed. Effectively, this
  99          * allows objects in Java to exist and then stop existing, only accessing
 100          * a native structure when it is needed and accessible on the Java end.
 101          * Since memory management in SquirrelJME's NanoCoat is more manual
 102          * with reference counting, there needs to be this information and
 103          * linkage in this way to prevent native structures from being
 104          * destroyed while a Java object still points to it.
 105          */
 106         SJME_FRONTEND_WEAK,
 107
 108         /** The number of bind types permitted. */
 109         SJME_FRONTEND_NUM_BIND_TYPE,
 110 } sjme_frontEnd_bindType;
 111
 112 /**
 113  * This structure stores any front end data as needed.
 114  *
 115  * @since 2023/12/14
 116  */
 117 typedef struct sjme_frontEnd sjme_frontEnd;
 118
 119 /**
 120  * This function is called when the front end binding needs to be obtained,
 121  * it may allocate and bind the data when this is called if applicable.
 122  *
 123  * @param owner The owning object of the front end.
 124  * @param frontEnd The front end data.
 125  * @param resultData The resultant bound data, which points to the native
 126  * binding reference.
 127  * @param action The action being performed on the instance.
 128  * @return Any resultant error, if any.
 129  * @since 2024/09/04
 130  */
 131 typedef sjme_errorCode (*sjme_frontEnd_binderFunc)(
 132         sjme_attrInNotNull sjme_pointer owner,
 133         sjme_attrInOutNotNull sjme_frontEndData* frontEnd,
 134         sjme_attrOutNotNull sjme_pointer* resultData,
 135         sjme_attrInValue sjme_frontEnd_bindAction action);
 136
 137 struct sjme_frontEnd
 138 {
 139         /** Any wrapper as needed. */
 140         sjme_frontEndWrapper wrapper;
 141
 142         /** Any data as needed. */
 143         sjme_frontEndData data;
 144
 145         /** The lock when binding/releasing is being performed on this. */
 146         sjme_thread_spinLock bindLock;
 147
 148         /** The binding type used. */
 149         sjme_frontEnd_bindType bindType;
 150
 151         /** Binder to call when the front end data is needed. */
 152         sjme_frontEnd_binderFunc bindHandler;
 153 };
 154
 155 /**
 156  * Wraps the given front end pointer.
 157  *
 158  * @param p The pointer to wrap.
 159  * @since 2023/12/08
 160  */
 161 #define SJME_FRONT_END_WRAP(p) ((sjme_frontEndWrapper)(p))
 162
 163 /**
 164  * This function is called when the front end binding needs to be obtained,
 165  * it may allocate and bind the data when this is called if applicable.
 166  *
 167  * @param owner The owning object of the front end.
 168  * @param frontEnd The front end data.
 169  * @param resultData The resultant bound data, which points to the native
 170  * binding reference.
 171  * @return Any resultant error, if any.
 172  * @since 2024/09/04
 173  */
 174 sjme_errorCode sjme_frontEnd_bind(
 175         sjme_attrInNotNull sjme_pointer owner,
 176         sjme_attrInOutNotNull sjme_frontEndData* frontEnd,
 177         sjme_attrOutNotNull sjme_pointer* resultData);
 178
 179 /**
 180  * This is called when a front end reference needs to be released.
 181  *
 182  * @param owner The owning object of the front end.
 183  * @param frontEnd The front end data.
 184  * @return Any resultant error, if any.
 185  * @since 2024/09/04
 186  */
 187 sjme_errorCode sjme_frontEnd_release(
 188         sjme_attrInNotNull sjme_pointer owner,
 189         sjme_attrInOutNotNull sjme_frontEndData* frontEnd);
 190
 191 /*--------------------------------------------------------------------------*/
 192
 193 /* Anti-C++. */
 194 #ifdef __cplusplus
 195         #ifdef SJME_CXX_SQUIRRELJME_FRONTEND_H
 196 }
 197                 #undef SJME_CXX_SQUIRRELJME_FRONTEND_H
 198                 #undef SJME_CXX_IS_EXTERNED
 199         #endif /* #ifdef SJME_CXX_SQUIRRELJME_FRONTEND_H */
 200 #endif /* #ifdef __cplusplus */
 201
 202 #endif /* SQUIRRELJME_FRONTEND_H */