Skip to content

Commit

Permalink
fix #3. Added ack. Updated the documentation and readmes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@ahmad88me
ahmad88me committed Jan 25, 2025
1 parent ee3d3b3 commit 2c708cf
Show file tree
Hide file tree
Showing 8 changed files with 371 additions and 120 deletions.
128 changes: 76 additions & 52 deletions README-pypi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,32 @@
<img src="https://github.com/ahmad88me/stiqueue/raw/main/stiqueue.svg" width="200">


# stiqueue
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.


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.
## Documentation
Explore the full [StiQueue Documentation](https://ahmad88me.github.io/stiqueue/) for in-depth code references and usage guides.


## Code Documentation
For detailed code documentation, visit the [StiQueue Documentation](https://ahmad88me.github.io/stiqueue/).

## 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` is the core of StiQueue and manages the messaging queue. It can be run directly with minimal setup.

```python src/stiqueue/sqserver.py --host 0.0.0.0 --port 1234 --debug```
#### Running the Server

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.
Once the code is downloaded, you can start the server with:

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

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



#### Usage
The following are the command-line options for running the server:
#### 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]
Expand All @@ -45,27 +46,25 @@ options:

### 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`.
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.

_Note that the `deq` method is blocking, which can save computation power compared
to the polling method._
**Blocking Dequeue**: The deq method is blocking, which is more resource-efficient than polling.


#### Client Code Sample
1. Import and initiate the client:
```
from stiqueue.sqclient import SQClient
c = SQClient()
```
2. Send a message
```
c.enq("Hello World!")
#### Quick Start
1. Initialize the Client:
```python
from stiqueue import SQClient
client = SQClient()
```
3. Fetch the message
2. Enqueue a Message:
```python
client.enq("Hello, World!")
```
hello_msg = c.deq().decode()
3. Dequeue a Message:
```python
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)
Expand All @@ -76,14 +75,22 @@ of running threads.

#### 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.
The following methods are supported by `stiqueue`:
* **`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
#### Basic Client Usage
The following is a simple example of how to use the `SQClient` to enqueue and dequeue messages from the server:

```python
Expand All @@ -93,32 +100,49 @@ from stiqueue import SQClient
client = 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](https://github.com/oeg-upm/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
[examples](https://github.com/ahmad88me/stiqueue/tree/main/example) directory.

### Running Tests
To run the unit tests for StiQueue, use the following command:
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](https://github.com/ahmad88me/stiqueue/tree/main/example) directory.


### 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! 🚀
129 changes: 76 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,38 @@

<img src="https://github.com/ahmad88me/stiqueue/raw/main/stiqueue.svg" width="200">

# stiqueue

![tests](../../actions/workflows/python-package.yml/badge.svg)
[![docs](../../actions/workflows/sphinx-docs.yml/badge.svg)](https://ahmad88me.github.io/stiqueue/)
[![PyPI version](https://badge.fury.io/py/stiqueue.svg?kill-cache=1)](https://badge.fury.io/py/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.
<img src="https://github.com/ahmad88me/stiqueue/raw/main/stiqueue.svg" width="200">


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.


## Code Documentation
For detailed code documentation, visit the [StiQueue Documentation](https://ahmad88me.github.io/stiqueue/).
## Documentation
Explore the full [StiQueue Documentation](https://ahmad88me.github.io/stiqueue/) 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` 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.
The `--debug` flag is useful during the first run to monitor incoming and outgoing messages.



#### Usage
The following are the command-line options for running the server:
#### 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]
Expand All @@ -46,27 +51,25 @@ options:

### 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`.
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.

_Note that the `deq` method is blocking, which can save computation power compared
to the polling method._
**Blocking Dequeue**: The deq method is blocking, which is more resource-efficient than polling.


#### Client Code Sample
1. Import and initiate the client:
```
from stiqueue.sqclient import SQClient
c = SQClient()
```
2. Send a message
```
c.enq("Hello World!")
#### Quick Start
1. Initialize the Client:
```python
from stiqueue import SQClient
client = SQClient()
```
3. Fetch the message
2. Enqueue a Message:
```python
client.enq("Hello, World!")
```
hello_msg = c.deq().decode()
3. Dequeue a Message:
```python
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)
Expand All @@ -77,14 +80,22 @@ of running threads.

#### 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.
The following methods are supported by `stiqueue`:
* **`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
#### Basic Client Usage
The following is a simple example of how to use the `SQClient` to enqueue and dequeue messages from the server:

```python
Expand All @@ -94,37 +105,49 @@ from stiqueue import SQClient
client = 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](https://github.com/oeg-upm/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
[examples](https://github.com/ahmad88me/stiqueue/tree/main/example) directory.

### Running Tests
To run the unit tests for StiQueue, use the following command:
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](https://github.com/ahmad88me/stiqueue/tree/main/example) directory.


### 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! 🚀
Loading

0 comments on commit 2c708cf

Please sign in to comment.