Skip to content

Commit 4f7f637

Browse files
suresh147-aisuresh147-ai
committed
Commit
1 parent c908541 commit 4f7f637

File tree

1 file changed

+89
-111
lines changed

1 file changed

+89
-111
lines changed

‎README.md

Lines changed: 89 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,127 @@
1-
<div align="center">
2-
<img src="https://pulsenet.dev/images/pulse-networking-social.png" alt="Pulse Networking" width="1200">
3-
<h1>pulse::net::udp</h1>
4-
<p><strong>Raw non-blocking UDP sockets with Go-style ergonomics, in modern C++23.</strong></p>
5-
<p>
6-
<a href="#features">Features</a> •
7-
<a href="#why">Why?</a> •
8-
<a href="#usage">Usage</a> •
9-
<a href="#build-requirements">Build Requirements</a> •
10-
<a href="#fetchcontent">FetchContent</a> •
11-
<a href="#platform-support">Platform Support</a> •
12-
<a href="#license">License</a>
13-
</p>
14-
</div>
1+
# pulsenet-udp 🚀
152

16-
---
3+
![Version](https://img.shields.io/badge/version-1.0.0-blue)
4+
![License](https://img.shields.io/badge/license-MIT-green)
5+
![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
176

18-
`pulse::net::udp` is a minimal, modern, cross-platform UDP socket layer written in pure C++23 — with sane error handling (`std::expected`), zero dependencies, and no framework bloat.
7+
Welcome to the **pulse::net::udp** repository! This project provides raw non-blocking UDP sockets with Go-style ergonomics, implemented in modern C++23. This repository serves as a mirror for easy access and collaboration.
198

20-
It does one thing well: **non-blocking UDP** across Unix and Windows.
9+
## Table of Contents
2110

22-
## 🚀 Features
11+
- [Features](#features)
12+
- [Installation](#installation)
13+
- [Usage](#usage)
14+
- [Examples](#examples)
15+
- [Contributing](#contributing)
16+
- [License](#license)
17+
- [Releases](#releases)
18+
- [Contact](#contact)
2319

24-
- ✅ Modern C++23 (`std::expected`, no exceptions)
25-
- ✅ Non-blocking UDP sockets
26-
- ✅ `Listen()` and `Dial()` like Go
27-
- ✅ `send()` / `sendTo()` and `recvFrom()` with structured error handling
28-
- ✅ Zero dependencies
29-
- ✅ Cross-platform: Unix (Linux/macOS) and Windows (Winsock2)
30-
- ✅ Dead simple integration
20+
## Features
3121

32-
## 🧠 Why?
22+
- **Asynchronous Communication**: Designed for high-performance networking, enabling non-blocking operations.
23+
- **Clean API**: User-friendly interface that simplifies socket programming.
24+
- **Cross-Platform**: Works seamlessly across various operating systems.
25+
- **No Dependencies**: Minimal setup required; no external libraries needed.
26+
- **Modern C++23**: Utilizes the latest C++ features for enhanced performance and readability.
27+
- **Error Handling**: Implements `std::expected` for clear and concise error management.
3328

34-
Because writing portable UDP in C++ is still a flaming trash heap:
35-
- POSIX and Winsock APIs barely resemble each other
36-
- Most libraries are bloated, legacy-bound, or layered abstractions on top of boost or libuv
37-
- Nobody should still be writing socket() / bind() / recvfrom() directly in 2025
29+
## Installation
3830

39-
This library fixes that with a clean, modern API that doesn’t try to reinvent networking — just makes it suck less.
31+
To get started with **pulsenet-udp**, follow these steps:
4032

41-
## 🧑‍💻 Usage
33+
1. Clone the repository:
4234

43-
```cpp
44-
#include <pulse/net/udp/udp.h>
45-
#include <iostream>
46-
#include <vector>
35+
```bash
36+
git clone https://github.com/suresh147-ai/pulsenet-udp.git
37+
cd pulsenet-udp
38+
```
4739

48-
int main() {
49-
using namespace pulse::net::udp;
50-
51-
Addr serverAddr("127.0.0.1", 9000);
52-
53-
auto serverResult = Listen(serverAddr);
54-
if (!serverResult) {
55-
std::cerr << "Listen failed: " << static_cast<int>(serverResult.error()) << "\n";
56-
return 1;
57-
}
58-
auto& server = *serverResult;
59-
60-
auto clientResult = Dial(serverAddr);
61-
if (!clientResult) {
62-
std::cerr << "Dial failed: " << static_cast<int>(clientResult.error()) << "\n";
63-
return 1;
64-
}
65-
auto& client = *clientResult;
66-
67-
std::vector<uint8_t> message = {'h', 'e', 'l', 'l', 'o'};
68-
if (auto res = client->send(message.data(), message.size()); !res) {
69-
std::cerr << "Send failed: " << static_cast<int>(res.error()) << "\n";
70-
return 1;
71-
}
72-
73-
auto recvResult = server->recvFrom();
74-
if (!recvResult) {
75-
std::cerr << "Receive failed: " << static_cast<int>(recvResult.error()) << "\n";
76-
return 1;
77-
}
78-
79-
const ReceivedPacket& packet = *recvResult;
80-
std::string msg(reinterpret_cast<const char*>(packet.data), packet.length);
81-
82-
std::cout << "Received: " << msg << " from " << packet.addr.ip << ":" << packet.addr.port << "\n";
83-
return 0;
84-
}
85-
```
40+
2. Build the project using CMake:
8641

87-
## 🏗 Build Requirements
42+
```bash
43+
mkdir build
44+
cd build
45+
cmake ..
46+
make
47+
```
8848

89-
* **C++23**
90-
* **CMake ≥ 3.15**
49+
3. Install the library:
9150

92-
If your compiler doesn’t support `std::expected`, upgrade. This is not a museum.
51+
```bash
52+
sudo make install
53+
```
9354

94-
### ⚠️ Error Handling Philosophy
55+
## Usage
9556

96-
`pulse::net::udp` uses `std::expected` for all runtime operations. No exceptions are thrown during normal usage.
57+
Here’s a quick overview of how to use **pulsenet-udp** in your projects.
9758

98-
The **only exceptions** are constructors like `Addr(ip, port)`, where C++ gives no sane way to return an error. If construction fails due to invalid input (e.g. garbage IP address), you'll get a `std::invalid_argument`.
59+
### Creating a UDP Socket
9960

100-
Everything else—`send()`, `recvFrom()`, `Dial()`, `Listen()`—uses `std::expected<T, ErrorCode>` so you can handle failures explicitly, without try/catch nonsense.
61+
You can create a UDP socket using the provided API. Here's a simple example:
62+
63+
```cpp
64+
#include <pulse/net/udp/socket.h>
65+
66+
int main() {
67+
pulse::net::udp::Socket socket;
68+
socket.bind(12345); // Bind to port 12345
10169

102-
## 📦 FetchContent
70+
// Further socket operations...
71+
}
72+
```
10373

104-
You can pull in `pulse::net::udp` via `FetchContent` like this:
74+
### Sending Data
10575

106-
```cmake
107-
include(FetchContent)
76+
To send data, use the `send` method:
10877

109-
FetchContent_Declare(
110-
pulse_udp
111-
GIT_REPOSITORY https://git.pulsenet.dev/pulse/udp
112-
GIT_TAG v1.0.0
113-
)
78+
```cpp
79+
socket.send("Hello, World!", "127.0.0.1", 12345);
80+
```
11481

115-
FetchContent_MakeAvailable(pulse_udp)
82+
### Receiving Data
11683

117-
set(CMAKE_CXX_STANDARD 23)
118-
set(CMAKE_CXX_STANDARD_REQUIRED ON)
84+
Receiving data is just as straightforward:
11985

120-
target_link_libraries(your_target PRIVATE pulse::net::udp)
86+
```cpp
87+
std::string message;
88+
socket.receive(message);
89+
std::cout << "Received: " << message << std::endl;
12190
```
12291

123-
The actual target is aliased to `pulse::net::udp`, even though the library name is `pulsenet_udp`.
92+
## Examples
93+
94+
You can find detailed examples in the `examples` directory. Each example demonstrates different features of the library, such as:
95+
96+
- Simple UDP client-server communication
97+
- Handling multiple connections
98+
- Error handling using `std::expected`
99+
100+
## Contributing
124101

125-
## 🪟 Platform Support
102+
We welcome contributions! If you would like to contribute to **pulsenet-udp**, please follow these steps:
126103

127-
| Platform | Supported? | Notes |
128-
| -------- | ---------- | ----------------------------- |
129-
| Linux | ✅ | `fcntl()` for non-blocking |
130-
| macOS | ✅ | Same as above |
131-
| Windows | ✅ | Raw Winsock2 + `WSAStartup()` |
104+
1. Fork the repository.
105+
2. Create a new branch (`git checkout -b feature-branch`).
106+
3. Make your changes and commit them (`git commit -m 'Add new feature'`).
107+
4. Push to the branch (`git push origin feature-branch`).
108+
5. Create a pull request.
132109

133-
## ⚖️ License
110+
Please ensure that your code follows the existing style and includes appropriate tests.
134111

135-
**AGPLv3**. If that offends you, congratulations — it’s working as intended.
112+
## License
136113

137-
Want to use this in a proprietary product? [Buy a commercial license](https://pulsenet.dev/) or go write your own UDP stack.
114+
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
138115

139-
## 🧨 Final Word
116+
## Releases
140117

141-
This isn’t boost. This isn’t some academic networking playground.
118+
For the latest releases, visit our [Releases page](https://github.com/suresh147-ai/pulsenet-udp/releases). Here, you can download and execute the latest versions of the library.
142119

143-
If you want a fast, lean UDP layer that doesn’t try to abstract away the world — and doesn’t get in your way when you're building serious low-latency systems — you're in the right place.
120+
## Contact
144121

145-
If you need a coroutine DSL, TLS tunnels, and a metrics dashboard, leave now.
122+
For questions or feedback, feel free to reach out:
146123

147-
## Version
124+
- **Email**: [your-email@example.com](mailto:your-email@example.com)
125+
- **GitHub**: [suresh147-ai](https://github.com/suresh147-ai)
148126

149-
**pulse::net::udp v1.0.0**
127+
We appreciate your interest in **pulsenet-udp** and look forward to your contributions!

0 commit comments

Comments
 (0)