Package io.roastedroot.proxywasm

Interface SharedQueueHandler

  • All Known Implementing Classes:
    SimpleSharedQueueHandler
    public interface SharedQueueHandler
    Defines the contract for handling shared message queues accessible by Proxy-WASM modules. Implementations of this interface manage the registration, resolution, and data manipulation (enqueue/dequeue) of queues that can potentially be accessed by multiple WASM modules or different instances of the same module, depending on the host environment's implementation.

    Shared queues provide a mechanism for inter-plugin communication or for passing data between different processing stages involving WASM modules.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static SharedQueueHandler DEFAULT
      A default, non-functional instance of SharedQueueHandler.

    • Method Summary

      All Methods Instance Methods Default Methods 
      Modifier and Type Method Description
      default byte[] dequeueSharedQueue​(int queueId)
      Removes and returns the next available message (byte array) from the front of the specified queue.
      default io.roastedroot.proxywasm.internal.WasmResult enqueueSharedQueue​(int queueId, byte[] value)
      Adds a message (byte array) to the end of the specified shared queue.
      default int registerSharedQueue​(QueueName name)
      Registers a shared queue with the given name, creating it if it doesn't exist, and returns its unique identifier (queue ID).
      default int resolveSharedQueue​(QueueName name)
      Resolves the unique identifier (queue ID) for a shared queue given its name.

    • Field Detail

      • DEFAULT

        static final SharedQueueHandler DEFAULT
        A default, non-functional instance of SharedQueueHandler. This instance throws WasmException with WasmResult.UNIMPLEMENTED for methods that register, resolve, or dequeue from queues, and returns WasmResult.UNIMPLEMENTED for enqueue operations. Useful as a placeholder or base when shared queue functionality is not supported or needed.

    • Method Detail

      • registerSharedQueue

        default int registerSharedQueue​(QueueName name)
                         throws WasmException
        Registers a shared queue with the given name, creating it if it doesn't exist, and returns its unique identifier (queue ID).
        Parameters:
        name - The QueueName uniquely identifying the queue (VM ID + queue name string).
        Returns:
        The unique integer ID assigned to the queue.
        Throws:
        WasmException - If the queue cannot be registered (e.g., resource limits, invalid name) or if the operation is unimplemented by the host.

      • resolveSharedQueue

        default int resolveSharedQueue​(QueueName name)
                        throws WasmException
        Resolves the unique identifier (queue ID) for a shared queue given its name. This does not create the queue if it doesn't exist.
        Parameters:
        name - The QueueName uniquely identifying the queue (VM ID + queue name string).
        Returns:
        The unique integer ID of the existing queue.
        Throws:
        WasmException - If the queue cannot be found (WasmResult.NOT_FOUND), or if the operation is unimplemented by the host.

      • dequeueSharedQueue

        default byte[] dequeueSharedQueue​(int queueId)
                           throws WasmException
        Removes and returns the next available message (byte array) from the front of the specified queue.
        Parameters:
        queueId - The unique integer ID of the target queue.
        Returns:
        The dequeued message data as a byte array.
        Throws:
        WasmException - If the queue is empty (WasmResult.EMPTY), the queue ID is invalid (WasmResult.NOT_FOUND), or the operation is unimplemented by the host.

      • enqueueSharedQueue

        default io.roastedroot.proxywasm.internal.WasmResult enqueueSharedQueue​(int queueId,
                                                                        byte[] value)
        Adds a message (byte array) to the end of the specified shared queue.
        Parameters:
        queueId - The unique integer ID of the target queue.
        value - The message data to enqueue.
        Returns:
        A WasmResult indicating the outcome (e.g., WasmResult.OK, WasmResult.NOT_FOUND, WasmResult.UNIMPLEMENTED).