modules/cldc-compact/src/main/java/cc/squirreljme/jvm/mle/TaskShelf.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 GNU General Public License v3+, or later.
   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.JarPackageBracket;
  13 import cc.squirreljme.jvm.mle.brackets.TaskBracket;
  14 import cc.squirreljme.jvm.mle.brackets.TracePointBracket;
  15 import cc.squirreljme.jvm.mle.constants.PipeErrorType;
  16 import cc.squirreljme.jvm.mle.constants.StandardPipeType;
  17 import cc.squirreljme.jvm.mle.constants.TaskPipeRedirectType;
  18 import cc.squirreljme.jvm.mle.constants.TaskStatusType;
  19 import cc.squirreljme.jvm.mle.exceptions.MLECallError;
  20 import cc.squirreljme.runtime.cldc.annotation.Api;
  21 import java.io.Closeable;
  22
  23 /**
  24  * This shelf allows for the management of tasks and otherwise.
  25  *
  26  * @since 2020/07/02
  27  */
  28 @SquirrelJMEVendorApi
  29 public final class TaskShelf
  30 {
  31         /**
  32          * Not used.
  33          *
  34          * @since 2020/07/02
  35          */
  36         private TaskShelf()
  37         {
  38         }
  39
  40         /**
  41          * Returns the tasks which are active.
  42          *
  43          * @return The active tasks.
  44          * @since 2020/07/09
  45          */
  46         @SquirrelJMEVendorApi
  47         public static native TaskBracket[] active();
  48
  49         /**
  50          * Returns the current task.
  51          *
  52          * @return The current task.
  53          * @since 2020/07/02
  54          */
  55         @SquirrelJMEVendorApi
  56         public static native TaskBracket current();
  57
  58         /**
  59          * Checks if the two given tasks are the same.
  60          *
  61          * @param __a The first.
  62          * @param __b The second.
  63          * @return If these tasks are the same.
  64          * @throws MLECallError If either argument is {@code null}.
  65          * @since 2020/07/02
  66          */
  67         @SquirrelJMEVendorApi
  68         public static native boolean equals(TaskBracket __a, TaskBracket __b)
  69                 throws MLECallError;
  70
  71         /**
  72          * Returns the current exit code of the given task.
  73          *
  74          * @param __task The task to get the exit code of.
  75          * @return The exit code, note that if it has not exited yet it may have
  76          * still set it via {@link ThreadShelf#setCurrentExitCode(int)}.
  77          * @throws MLECallError If the task is not valid.
  78          * @since 2020/07/02
  79          */
  80         @SquirrelJMEVendorApi
  81         public static native int exitCode(TaskBracket __task)
  82                 throws MLECallError;
  83
  84         /**
  85          * Gets the trace that was set by the program.
  86          *
  87          * @param __task The task to get the trace from.
  88          * @param __outMessage The output array to store the message.
  89          * @return The trace for the given task or {@code null} if there is none.
  90          * @throws MLECallError On null arguments, if the task is not valid, or
  91          * if {@code __outMessage} is too small.
  92          * @since 2020/07/02
  93          */
  94         @SquirrelJMEVendorApi
  95         public static native TracePointBracket[] getTrace(TaskBracket __task,
  96                 String[] __outMessage)
  97                 throws MLECallError;
  98
  99         /**
 100          * If a task was started with {@link TaskPipeRedirectType#BUFFER} then the
 101          * contents of the task's output buffer can be read with this.
 102          *
 103          * This call must never block.
 104          *
 105          * End-of-file is reached when the buffer is completely drained and the
 106          * task either the task is {@link TaskStatusType#EXITED} or
 107          * {@link Closeable#close()} was called on the output pipe.
 108          *
 109          * @param __task The task to
 110          * @param __fd The {@link StandardPipeType} to read from.
 111          * @param __b The buffer to read into.
 112          * @param __o The offset.
 113          * @param __l The length.
 114          * @return One of {@link PipeErrorType} or the number of bytes which were
 115          * read.
 116          * @throws MLECallError If the task does not use buffering for the given
 117          * descriptor, {@code __fd} is not valid, or the offset and/or length
 118          * are negative or exceed the array bounds.
 119          * @since 2020/07/02
 120          */
 121         @SquirrelJMEVendorApi
 122         public static native int read(TaskBracket __task, int __fd,
 123                 byte[] __b, int __o, int __l)
 124                 throws MLECallError;
 125
 126         /**
 127          * Launches another task with the specified class path, main class, and
 128          * otherwise.
 129          *
 130          * The first JAR in the classpath must be the same as our current classpath
 131          * to prevent the CLDC library from being switched out.
 132          *
 133          * Note that the first task implicitly created by the virtual machine
 134          * will have its standard input be read from the standard input, whereas
 135          * for sub-tasks it will be sourced from a buffer.
 136          *
 137          * @param __classPath The class path that the launched application should
 138          * use.
 139          * @param __mainClass The main class to execute, this must be a class which
 140          * contains {@code static void main(String[] __args)}.
 141          * @param __args The arguments to the main class.
 142          * @param __sysPropPairs System property pairs, even values are keys and
 143          * odd values are values. This array must always be a multiple of two.
 144          * @param __stdOut The {@link TaskPipeRedirectType} for standard output.
 145          * @param __stdErr The {@link TaskPipeRedirectType} for standard error.
 146          * @return The bracket that represents the task.
 147          * @throws MLECallError If any argument is {@code null}, or an array
 148          * contains a {@code null} value, the {@code __sysPropPairs} is not a
 149          * multiple of two, {@code __classPath[0]} is not the same Jar package
 150          * as our own classpath's first JAR, if the task could not be created,
 151          * or if either the {@code __stdOut} or {@code __stdErr} redirect types
 152          * are not valid.
 153          * @since 2020/07/02
 154          */
 155         @SquirrelJMEVendorApi
 156         public static native TaskBracket start(
 157                 JarPackageBracket[] __classPath, String __mainClass, String[] __args,
 158                 String[] __sysPropPairs, int __stdOut, int __stdErr)
 159                 throws MLECallError;
 160
 161         /**
 162          * Returns the status of the given task.
 163          *
 164          * @param __task The task to request the status of.
 165          * @return One of {@link TaskStatusType}.
 166          * @throws MLECallError If the task is not valid.
 167          * @since 2020/07/02
 168          */
 169         @SquirrelJMEVendorApi
 170         public static native int status(TaskBracket __task)
 171                 throws MLECallError;
 172 }