StarQueue

An extremely simple message queue server for distributed applications and microservices, StarQueue has been designed with simplicity in mind. It works as a remote FIFO queue that can perform insertion and retrieval of string values. It's extremely fast and has been designed from the ground up to be used with distributed applications and microservices. For long term storage, cyclical checkpoint saves are executed.

Building and installation

To build StarQueue, clone this repository and run make in it. C++11 is required.
To install StarQueue, run make install.
To uninstall StarQueue, simply run make uninstall. You will also manually have to delete any checkpoint files you may have created while using StarQueue.

Usage

StarQueue can be used both as a local or a remote message queue. In both cases, running starqueue starts the StarQueue server on the default StarQueue port (17827) using the file starqueue.qu on your home directory as its checkpoint file. Check starqueue --help for information on how to launch StarQueue with a custom configuration.

Programs can connect to StarQueue to access the message queue system using its port and IP address (localhost for local systems). To communicate with StarQueue, 6 commands can be used, sent via a normal TCP socket stream. Sent messages must be terminated using the \r\n character sequence. Messages sent by CoralDB always end with said character sequence, too.

A client must establish a new connection to StarQueue every time it wants to send a command. Likewise, StarQueue closes the connection after a response has been sent to the client.

Command Index

Command	Description
ENQUEUE	Enqueues a message into the queue.
DEQUEUE	Dequeues and retrieves the next message from the queue.
SIZE	Returns the size of the queue.
CLEAR	Empties que queue.
PING	Checks if the database is online.
CHECKPOINT	Forces a queue checkpoint save.

ENQUEUE

Usage: ENQUEUE "value"

ENQUEUE enqueues "value" into the queue. Values must be enclosed in double-quotes ("). Double-quotes inside a value may be escaped using the \" character sequence.

Responses:
- OK. for successful operations.
- ERROR. for unsuccessful operations.

DEQUEUE

Usage: DEQUEUE

DEQUEUE gets the next value from the queue. The operation fails if the queue is empty.

Responses:
- "value" for successful operations, where value is the value retrieved. Note that the value is enclosed in double-quotes.
- ERROR. for unsuccessful operations.

SIZE

Usage: SIZE

SIZE returns the size of the queue as an integer.

Responses:
- The queue size (for example, 1293).

CLEAR

Usage: CLEAR

CLEAR empties the queue.

Responses:
- OK.

PING

Usage: PING

PING can be used to check if StarQueue is alive.

Responses:
- OK. for successful operations.

CHECKPOINT

Usage: CHECKPOINT

CHECKPOINT can be used to trigger a checkpoint save.

Responses:
- OK. once the checkpoint save has finished.

Example Session

In this example, \r\n at the end of lines are omitted.

Client:    ENQUEUE "hi there"
StarQueue: OK.
Client:    ENQUEUE "gotta go!"
StarQueue: OK.
Client:    ENQUEUE "bye!"
StarQueue: OK.
Client:    DEQUEUE
StarQueue: "hi there"
Client:    SIZE
StarQueue: 2
Client:    DEQUEUE
StarQueue: "gotta go!"
Client:    CLEAR
StarQueue: OK.
Client:    DEQUEUE
StarQueue: ERROR.

I need help! I want to contribute!

If you need help on using StarQueue, please open an issue here and I will try to address it as soon as possible.

Contributions are also more than welcome! Feel free to submit pull requests!

License

StarQueue is released under the BSD 2-Clause License.

Lartu/starqueue