modules/cldc-compact/src/main/java/cc/squirreljme/jvm/mle/ThreadShelf.java

   1 // -*- Mode: Java; 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 package cc.squirreljme.jvm.mle;
  11
  12 import cc.squirreljme.jvm.mle.brackets.TaskBracket;
  13 import cc.squirreljme.jvm.mle.brackets.TracePointBracket;
  14 import cc.squirreljme.jvm.mle.brackets.VMThreadBracket;
  15 import cc.squirreljme.jvm.mle.constants.ThreadModelType;
  16 import cc.squirreljme.jvm.mle.exceptions.MLECallError;
  17 import cc.squirreljme.runtime.cldc.annotation.Api;
  18 import cc.squirreljme.runtime.cldc.annotation.SquirrelJMEVendorApi;
  19 import org.intellij.lang.annotations.Flow;
  20 import org.intellij.lang.annotations.MagicConstant;
  21 import org.jetbrains.annotations.Blocking;
  22 import org.jetbrains.annotations.CheckReturnValue;
  23 import org.jetbrains.annotations.NotNull;
  24 import org.jetbrains.annotations.Range;
  25
  26 /**
  27  * This shelf handles everything regarding threading and otherwise.
  28  *
  29  * @see VMThreadBracket
  30  * @since 2020/06/17
  31  */
  32 @SuppressWarnings("UnstableApiUsage")
  33 @SquirrelJMEVendorApi
  34 public final class ThreadShelf
  35 {
  36         /**
  37          * Returns the number of alive threads.
  38          *
  39          * @param __includeMain Include main threads?
  40          * @param __includeDaemon Include daemon threads?
  41          * @return The number of alive threads.
  42          * @since 2020/06/17
  43          */
  44         @SquirrelJMEVendorApi
  45         public static native int aliveThreadCount(boolean __includeMain,
  46                 boolean __includeDaemon);
  47
  48         /**
  49          * Creates a virtual machine thread for the given Java thread.
  50          *
  51          * @param __javaThread The Java thread to create under.
  52          * @param __name The name of this thread.
  53          * @return The virtual machine thread.
  54          * @throws MLECallError If {@code __javaThread} is null.
  55          * @since 2020/06/17
  56          */
  57         @SquirrelJMEVendorApi
  58         public static native VMThreadBracket createVMThread(
  59                 @Flow(target = "this._vmThread") @NotNull Thread __javaThread,
  60                 String __name)
  61                 throws MLECallError;
  62
  63         /**
  64          * Returns the exit code for the current process.
  65          *
  66          * @return The exit code for the current process.
  67          * @since 2020/06/17
  68          */
  69         @SquirrelJMEVendorApi
  70         public static native int currentExitCode();
  71
  72         /**
  73          * Returns the current Java thread.
  74          *
  75          * @return The current {@link Thread}.
  76          * @since 2020/06/17
  77          */
  78         @SquirrelJMEVendorApi
  79         public static native Thread currentJavaThread();
  80
  81         /**
  82          * Returns the current virtual machine thread.
  83          *
  84          * @return The current virtual machine thread.
  85          * @since 2021/05/08
  86          */
  87         @SquirrelJMEVendorApi
  88         public static native VMThreadBracket currentVMThread();
  89
  90         /**
  91          * Checks if these two threads are the same.
  92          *
  93          * @param __a The first thread.
  94          * @param __b The second thread.
  95          * @return If these are the same thread.
  96          * @throws MLECallError If either arguments are null.
  97          * @since 2021/05/08
  98          */
  99         @SquirrelJMEVendorApi
 100         public static native boolean equals(VMThreadBracket __a,
 101                 VMThreadBracket __b)
 102                 throws MLECallError;
 103
 104         /**
 105          * Returns whether the interrupt flag was raised and clears it.
 106          *
 107          * @param __javaThread The Java thread.
 108          * @return If the thread was interrupted.
 109          * @throws MLECallError If {@code __javaThread} is null.
 110          * @since 2020/06/17
 111          */
 112         @SquirrelJMEVendorApi
 113         public static native boolean javaThreadClearInterrupt(
 114                 @NotNull Thread __javaThread)
 115                 throws MLECallError;
 116
 117         /**
 118          * Marks the thread as being started.
 119          *
 120          * @param __javaThread The thread to mark started.
 121          * @throws MLECallError If {@code __javaThread} is null.
 122          * @since 2020/06/17
 123          */
 124         @SquirrelJMEVendorApi
 125         public static native void javaThreadFlagStarted(
 126                 @NotNull Thread __javaThread)
 127                 throws MLECallError;
 128
 129         /**
 130          * Has this Java thread been started?
 131          *
 132          * @param __javaThread The Java thread.
 133          * @return If this thread has been started.
 134          * @throws MLECallError If {@code __javaThread} is null.
 135          * @since 2020/06/17
 136          */
 137         @SquirrelJMEVendorApi
 138         @Flow(source = "this._started")
 139         public static native boolean javaThreadIsStarted(
 140                 @NotNull Thread __javaThread)
 141                 throws MLECallError;
 142
 143         /**
 144          * Returns the runnable for the given Java thread.
 145          *
 146          * @param __javaThread The Java thread.
 147          * @return The {@link Runnable} for the given thread.
 148          * @throws MLECallError If {@code __javaThread} is null.
 149          * @since 2020/06/17
 150          */
 151
 152         @SquirrelJMEVendorApi
 153         @Flow(source = "this._runnable")
 154         public static native Runnable javaThreadRunnable(
 155                 @NotNull Thread __javaThread)
 156                 throws MLECallError;
 157
 158         /**
 159          * Sets if the thread is alive or not.
 160          *
 161          * @param __javaThread The Java thread.
 162          * @param __set If this is to be alive or not. If this is {@code true}
 163          * then the active count goes up, otherwise it shall go down.
 164          * @throws MLECallError If {@code __javaThread} is null.
 165          * @since 2020/06/17
 166          */
 167         @SquirrelJMEVendorApi
 168         public static native void javaThreadSetAlive(@NotNull Thread __javaThread,
 169                 boolean __set)
 170                 throws MLECallError;
 171
 172         /**
 173          * Sets the thread to be a daemon thread, it cannot be started.
 174          *
 175          * @param __javaThread The thread to set as a daemon thread.
 176          * @throws MLECallError If {@code __javaThread} is null or is already
 177          * started.
 178          * @since 2020/09/12
 179          */
 180         @SquirrelJMEVendorApi
 181         public static native void javaThreadSetDaemon(@NotNull Thread __javaThread)
 182                 throws MLECallError;
 183
 184         /**
 185          * Returns the {@link ThreadModelType} of the virtual machine.
 186          *
 187          * @return The {@link ThreadModelType} of the virtual machine.
 188          * @since 2021/05/07
 189          */
 190         @SquirrelJMEVendorApi
 191         @MagicConstant(valuesFromClass = ThreadModelType.class)
 192         public static native int model();
 193
 194         /**
 195          * Runs the main entry point for the current process and gives it all of
 196          * the arguments that were specified on program initialization.
 197          *
 198          * @since 2020/06/17
 199          */
 200         @SquirrelJMEVendorApi
 201         public static native void runProcessMain();
 202
 203         /**
 204          * Sets the current process exit code.
 205          *
 206          * @param __code The exit code to use.
 207          * @since 2020/06/17
 208          */
 209         @SquirrelJMEVendorApi
 210         public static native void setCurrentExitCode(int __code);
 211
 212         /**
 213          * Sets the trace of the current task so that it can be requested by
 214          * another or launching program.
 215          *
 216          * @param __message The message of the trace.
 217          * @param __trace The trace to set.
 218          * @throws MLECallError If {@code __message} is {@code null}, or
 219          * {@code __trace} or any element within is {@code null}.
 220          * @since 2020/07/02
 221          */
 222         @SquirrelJMEVendorApi
 223         public static native void setTrace(@NotNull String __message,
 224                 @NotNull TracePointBracket[] __trace)
 225                 throws MLECallError;
 226
 227         /**
 228          * Sleeps the current thread for the given amount of time.
 229          *
 230          * If both times are zero, this means to yield the thread (give up its
 231          * current execution context).
 232          *
 233          * If SquirrelJME is running in cooperative
 234          * single threaded mode, this will relinquish control of the current
 235          * thread.
 236          *
 237          * @param __ms The number of milliseconds.
 238          * @param __ns The number of nanoseconds.
 239          * @return {@code true} if the thread was interrupted.
 240          * @throws MLECallError If either value is negative or the nanoseconds is
 241          * out of range.
 242          * @since 2020/06/17
 243          */
 244         @SquirrelJMEVendorApi
 245         @Blocking
 246         public static native boolean sleep(
 247                 @Range(from = 0, to = Integer.MAX_VALUE) int __ms,
 248                 @Range(from = 0, to = 999999) int __ns)
 249                 throws MLECallError;
 250
 251         /**
 252          * Returns the Java thread for the VM thread.
 253          *
 254          * @param __vmThread The VM thread.
 255          * @return The Java thread which belongs to this thread.
 256          * @throws MLECallError If {@code __thread} is null.
 257          * @since 2020/06/17
 258          */
 259         @SquirrelJMEVendorApi
 260         public static native Thread toJavaThread(
 261                 @NotNull VMThreadBracket __vmThread)
 262                 throws MLECallError;
 263
 264         /**
 265          * Returns the virtual machine thread from the given Java thread.
 266          *
 267          * @param __thread The Java thread.
 268          * @return The VM thread for this thread.
 269          * @throws MLECallError If {@code __thread} is null.
 270          * @since 2020/06/17
 271          */
 272         @SquirrelJMEVendorApi
 273         @Flow(source = "this._vmThread")
 274         public static native VMThreadBracket toVMThread(
 275                 @NotNull Thread __thread)
 276                 throws MLECallError;
 277
 278         /**
 279          * Signals that the thread has ended and is no longer considered to be
 280          * alive.
 281          *
 282          * @param __vmThread The virtual machine thread.
 283          * @throws MLECallError If {@code __vmThread} is null.
 284          * @since 2021/03/14
 285          */
 286         @SquirrelJMEVendorApi
 287         public static native void vmThreadEnd(
 288                 @NotNull VMThreadBracket __vmThread)
 289                 throws MLECallError;
 290
 291         /**
 292          * Returns the thread ID for the given thread.
 293          *
 294          * @param __vmThread The virtual machine thread.
 295          * @return The thread ID.
 296          * @throws MLECallError If {@code __vmThread} is null.
 297          * @since 2020/06/17
 298          */
 299         @SquirrelJMEVendorApi
 300         public static native int vmThreadId(
 301                 @NotNull VMThreadBracket __vmThread)
 302                 throws MLECallError;
 303
 304         /**
 305          * Performs a hardware interrupt on the thread.
 306          *
 307          * @param __vmThread The virtual machine thread.
 308          * @throws MLECallError If {@code __vmThread} is null.
 309          * @since 2020/06/17
 310          */
 311         @SquirrelJMEVendorApi
 312         public static native void vmThreadInterrupt(
 313                 @NotNull VMThreadBracket __vmThread)
 314                 throws MLECallError;
 315
 316         /**
 317          * Checks if the given thread is a main thread.
 318          *
 319          * @param __vmThread The thread to check.
 320          * @return {@code true} if the given thread is a main thread.
 321          * @throws MLECallError If {@code __vmThread} is null.
 322          * @since 2020/06/17
 323          */
 324         @SquirrelJMEVendorApi
 325         public static native boolean vmThreadIsMain(
 326                 @NotNull VMThreadBracket __vmThread)
 327                 throws MLECallError;
 328
 329         /**
 330          * Sets the thread priority in the same manner as
 331          * {@link Thread#setPriority(int)} if this is supported by the hardware.
 332          *
 333          * This may or may not be supported and should only be used as a hint and
 334          * not a guarantee.
 335          *
 336          * @param __vmThread The virtual machine thread.
 337          * @param __p The priority to set, this will be the same as
 338          * {@link Thread#setPriority(int)}.
 339          * @throws MLECallError If {@code __vmThread} is null or {@code __p} is
 340          * not within {@link Thread#MIN_PRIORITY} and {@link Thread#MAX_PRIORITY}
 341          * inclusive.
 342          * @since 2020/06/17
 343          */
 344         @SquirrelJMEVendorApi
 345         public static native void vmThreadSetPriority(
 346                 @NotNull VMThreadBracket __vmThread, int __p)
 347                 throws MLECallError;
 348
 349         /**
 350          * Performs the actual start of the given thread.
 351          *
 352          * @param __vmThread The thread to start.
 353          * @return If the start of the thread succeeded.
 354          * @throws MLECallError If {@code __vmThread} is null.
 355          * @since 2020/06/17
 356          */
 357         @SquirrelJMEVendorApi
 358         public static native boolean vmThreadStart(
 359                 @NotNull VMThreadBracket __vmThread)
 360                 throws MLECallError;
 361
 362         /**
 363          * Returns the task that owns the given thread.
 364          *
 365          * @param __vmThread The thread to get the task of.
 366          * @return The task for the given thread.
 367          * @throws MLECallError If the thread is not valid.
 368          * @since 2021/05/08
 369          */
 370         @SquirrelJMEVendorApi
 371         public static native TaskBracket vmThreadTask(
 372                 @NotNull VMThreadBracket __vmThread)
 373                 throws MLECallError;
 374
 375         /**
 376          * Waits for the state of threads to be updated, or just times out.
 377          *
 378          * A thread update is when another thread becomes alive, becomes dead,
 379          * or is started.
 380          *
 381          * If waiting and SquirrelJME is running in cooperative
 382          * single threaded mode, this will relinquish control of the current
 383          * thread.
 384          *
 385          * @param __ms The amount of time to wait for.
 386          * @return If the thread was interrupted while waiting.
 387          * @throws MLECallError If {@code __ms} is negative.
 388          * @since 2020/06/17
 389          */
 390         @SquirrelJMEVendorApi
 391         @Blocking
 392         public static native boolean waitForUpdate(int __ms)
 393                 throws MLECallError;
 394 }