-
-

stiqueue

-

StiQueue, which stands for “stick queue,” is inspired by the simplicity of a stick figure. Just as a stick figure represents simplicity in design, StiQueue is designed to be a simple, lightweight messaging queue system that is both easy to use and flexible.

-
-

Code Documentation

-

For detailed code documentation, visit the StiQueue Documentation.

+

StiQueue, short for “stick queue,” is inspired by the simplicity of a stick figure. +Just as a stick figure represents minimalism and clarity, StiQueue is a lightweight messaging queue system +designed to be simple, flexible, and easy to use.

+
+

Documentation

+

Explore the full StiQueue Documentation for in-depth code references and usage guides.

-
-

Guide

+
+

Getting Started

-

SQServer

-

You can run the SQServer directly without writing any additional code. The server will handle the messaging queue. -Once the code is downloaded, you can start the server as follows:

+

SQServer

+

SQServer is the core of StiQueue and manages the messaging queue. It can be run directly with minimal setup.

+
+

Running the Server

+

Once the code is downloaded, you can start the server with:

python src/stiqueue/sqserver.py --host 0.0.0.0 --port 1234 --debug

-

It is recommended to use the --debug flag during the first run to monitor when the server receives a message or -when a message leaves the queue.

-
-

Usage

-

The following are the command-line options for running the server:

+

The --debug flag is useful during the first run to monitor incoming and outgoing messages.

+
+
+

Server Options

+

Below are the available command-line options for the server:

usage: StiQueue Server [-h] [--debug] [--host HOST] [--port PORT] [--buff-size BUFF_SIZE]
 
 A message queue server
@@ -65,31 +67,30 @@ 
Usage
-

SQClient

-

The SQClient is intended for use within your code. Once you install the stiqueue package in your Python project, -you can use the client to send and receive messages from the messaging queue. Ensure that the client’s host and port -match those of your SQServer.

-

Note that the ``deq`` method is blocking, which can save computation power compared -to the polling method.

-
-

Client Code Sample

+

SQClient

+

The SQClient allows you to interact with the server to enqueue (send) and dequeue (receive) messages. +Ensure the host and port of the client match the server configuration.

+

Blocking Dequeue: The deq method is blocking, which is more resource-efficient than polling.

+
+

Quick Start

    -

  1. Import and initiate the client:

    2. +

  2. Initialize the Client:

-
from stiqueue.sqclient import SQClient
-c = SQClient()
+
from stiqueue import SQClient
+client = SQClient()
 

 

 
    
-
  1. Send a message
    2. 
+
  2. Enqueue a Message:
    3. 
 

-
c.enq("Hello World!")
+
client.enq("Hello, World!")
 

 

 
    
-
  1. Fetch the message
    2. 
+
  2. Dequeue a Message:
    3. 
 

-
hello_msg = c.deq().decode()
+
msg = client.deq().decode()
+print("Received:", msg)
 

 

 
Often, the client that sends the messages is different from the one receiving them. For instance, one client (or app)
@@ -98,19 +99,25 @@ 
Client Code Sample
-
Methods

+
Methods

 
The following methods are supported by stiqueue:

 
    
-
  • ``enq``: Add a message to the queue (enqueue).
    • 
-
  • ``deq``: Retrieve a message from the queue (dequeue).
    • 
-
  • ``cnt``: Get the number of items in the queue.
    • 
+
  • ``enq(msg: bytes)``: Adds a message to the queue.
    • 
+
  • ``deq() -> bytes``: Retrieves the next message from the queue (blocking call).
    • 
+
  • ``cnt() -> int``: Returns the number of messages currently in the queue.
    • 
+
  • ``ack()``: Acknowledges a message when ack_required=True. If not acknowledged within ack_timeout,
+the server re-enqueues the message.
    • 
 

+

+
Note: When ack_required=True and the client process crashes after calling deq, messages are automatically
+re-queued to ensure they are not lost.

+
-

Examples

-
-

Client example

+

Examples

+
+

Basic Client Usage

The following is a simple example of how to use the SQClient to enqueue and dequeue messages from the server:

from stiqueue import SQClient
 
@@ -118,35 +125,49 @@ 
Client exampleclient = SQClient()
 
 # Enqueue messages
-client.enq(b"This is message one")
-client.enq(b"This is message two")
-client.enq(b"This is message three")
-
-# Dequeue and print messages
-msg1 = client.deq().decode()
-print("msg1:", msg1)
+client.enq(b"First message")
+client.enq(b"Second message")
 
-msg2 = client.deq().decode()
-print("msg2:", msg2)
-
-msg3 = client.deq().decode()
-print("msg3:", msg3)
+# Dequeue and process messages
+print(client.deq().decode())  # Output: First message
+print(client.deq().decode())  # Output: Second message

Note: The decode() method is used because the deq() method returns the messages as bytes, which need to be decoded to a string for readability.

+
+

Using a Thread Pool

+

You can integrate a thread pool, such as TPool, for managing concurrent client operations.

+
-

Extending StiQueue

-

While StiQueue is designed to be simple and flexible, you might want to extend its functionality for specific use cases. -We provide examples of how to extend StiQueue with additional features in the +

Extending StiQueue

+

StiQueue is designed to be flexible and extensible. You can add custom functionality to the server or client as needed. +Examples of extending StiQueue are available in the examples directory.

-
-

Running Tests

-

To run the unit tests for StiQueue, use the following command:

+
+

Testing

+

Run the unit tests to ensure everything is working as expected.

python -m unittest discover

+
+
+

Run a Specific Test

+

Replace <test_file_name> with the desired test file:

+
python -m unittest tests.<test_file_name>
+
+
+
+
+
+

Key Highlights

+
    +

  • Lightweight and Flexible: Minimal dependencies and easy to integrate.

    • +

  • Blocking Dequeue: Efficient for resource-limited systems.

    • +

  • Reliable Messaging: Optional message acknowledgments to ensure no data loss.

    • +
+

If you’d like additional improvements or refinements, feel free to ask! 🚀

Contents:

    @@ -164,11 +185,6 @@

    Running Tests -

    Indices and tables

    • Index

    • Module Index

      • diff --git a/docs/modules.html b/docs/modules.html index 6e57bbf..f33fbcd 100644 --- a/docs/modules.html +++ b/docs/modules.html @@ -42,6 +42,8 @@

      srcSQClient.socket
    • SQClient.buff_size
    • SQClient.logger
      • +
    • SQClient.ack_required
      • +
    • SQClient.ack()
    • SQClient.cnt()
    • SQClient.connect()
    • SQClient.deq()
      • diff --git a/docs/objects.inv b/docs/objects.inv index 45e5d281d92516a5f83fb474510f65503c56b411..1b98316327fe8eafcd2f039b3e2edadb6ef71f87 100644 GIT binary patch delta 347 zcmV-h0i^!51Iq)Dd4F=kAP|P{c?xFQYizxGZF}gUGdey%24PJY2_!7E+NW<4NECH! zE4Q%w|KBbfX3>h)frA;gObSqzG>1j4xsyPi369yy*7CuJ^GA|rcy61mS1*&FNs373 zXZG8^8D+bnHrPt@JIsZF)(Hc=r%-E+*f08~N)l}4L1e5uP4OcJ8eCanhq#fvXttAa8sw7P#BsM!ww&ioMNe@8;}>`4tXJe@~su&e67%##McdbA@Ghk1oH{zCN7qE+eji8wWGwm$ZcGL7lb}y_xAmnr?UYmLCtbFdZwFq>2Cl delta 325 zcmV-L0lNOn1GNK?d4Fz$Fbsz8JVm7KO1EBnop#t^Ql~xu3W*C*LjrNw%AS5e0wrzL zt;-GD|Nq&sLePq)g%(!WFeyM;Qg@q5^Hu_RCOB0~TgeBPP9I5{;JIzJ`*@lCOj1O$ zKC|EUt@3ui&rp2BK%mwdk+&A^r7(X2u%+gAo3&EFA^;qk2!FG{=m9`Q3{YycQOlRQ zD8NJ^YHi|XKu|pU61L1JvqG!?uLCtZz#oQzBdux)*q8W*Yev#FnR26wy!t4VN}7Yb z5ckLn`I8$h^YOJtXA;-f|B;?|!XcPXFgJ0b#Nl>hZpIa$gyL`v4>M(* - + @@ -45,7 +45,7 @@

      Submodules
      -class stiqueue.sqclient.SQClient(host='127.0.0.1', port=1234, logger=None, buff_size=None)[source]
      +class stiqueue.sqclient.SQClient(host='127.0.0.1', port=1234, logger=None, buff_size=None, ack_required=True)[source]

      Bases: object

      A client that connects to a message queue server for enqueuing, dequeuing, and retrieving the count of messages.

      @@ -103,6 +103,23 @@

      Submodules +
      +ack_required
      +

      Indicates whether an acknowledgment is required after the client receives the message.

      +
      +
      Type:
      +

      bool

      +
      +
      +

      + +
      +
      +ack()[source]
      +

      Sends an acknowledgement request to the server.

      +
      +
      cnt()[source]
      @@ -219,7 +236,7 @@

      Navigation

      Related Topics