# UV module

<a id="uvmodule"></a>

# UV module

The `uv` module contains C++ wrappers for `libuv`.

## Classes

| Name | Description |
|------|-------------|
| [`Handle`](https://auscaster.com/icey/docs/api-reference/icy-uv-Handle.md#handle-6) | Wrapper class for managing `uv_handle_t` variants. |
| [`ScopedLoop`](https://auscaster.com/icey/docs/api-reference/icy-uv-ScopedLoop.md#scopedloop) | RAII wrapper for a libuv event loop. Automatically closes and deletes the loop on destruction. |
| [`HandleStorage`](https://auscaster.com/icey/docs/api-reference/icy-uv-HandleStorage.md#handlestorage-1) | Extra storage placed around a raw `libuv` handle for close-time cleanup hooks. |
| [`Context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Context.md#context-2) | Shared `libuv` handle context. |
| [`BasicEvent`](https://auscaster.com/icey/docs/api-reference/icy-uv-BasicEvent.md#basicevent) | Default request callback event carrying a libuv status code. |
| [`Request`](https://auscaster.com/icey/docs/api-reference/icy-uv-Request.md#request-2) | Wrapper class for managing `uv_req_t` variants. |
| [`ConnectReq`](https://auscaster.com/icey/docs/api-reference/icy-uv-ConnectReq.md#connectreq) | Asynchronous connection request for TCP sockets and named pipes. |
| [`GetAddrInfoEvent`](https://auscaster.com/icey/docs/api-reference/icy-uv-GetAddrInfoEvent.md#getaddrinfoevent) | Callback event delivered when a [`GetAddrInfoReq`](https://auscaster.com/icey/docs/api-reference/icy-uv-GetAddrInfoReq.md#getaddrinforeq) resolves. |
| [`GetAddrInfoReq`](https://auscaster.com/icey/docs/api-reference/icy-uv-GetAddrInfoReq.md#getaddrinforeq) | DNS resolver request to get the IP address of a hostname. |

## Typedefs

| Return | Name | Description |
|--------|------|-------------|
| `uv_loop_t` | [`Loop`](#loop-1)  | Alias for a `libuv` event loop instance. |

---

<a id="loop-1"></a>

### Loop

```cpp
using Loop = uv_loop_t
```

[Defined in src/base/include/icy/loop.h:29](https://github.com/auscaster/icey/blob/main/src/base/include/icy/loop.h#L29)

Alias for a `libuv` event loop instance.

## Functions

| Return | Name | Description |
|--------|------|-------------|
| [`Loop`](#loop-1) * | [`defaultLoop`](#defaultloop) `inline` | Returns the process-wide default libuv event loop. |
| `void` | [`runLoop`](#runloop) `inline` | Runs the given event loop using the specified run mode. Blocks until the loop exits (when using `UV_RUN_DEFAULT`). |
| `void` | [`stopLoop`](#stoploop) `inline` | Stops the given event loop, causing `uv_run` to return after the current iteration. |
| [`Loop`](#loop-1) * | [`createLoop`](#createloop) `inline` | Allocates and initializes a new libuv event loop. The caller is responsible for closing and deleting the returned loop. |
| `bool` | [`closeLoop`](#closeloop) `inline` | Closes the given event loop, releasing internal resources. All handles must be closed before calling this. |
| [`HandleStorage`](https://auscaster.com/icey/docs/api-reference/icy-uv-HandleStorage.md#handlestorage-1)< T > * | [`handleStorage`](#handlestorage) `inline` | Returns the extended storage wrapper that owns `handle`. |
| `void` | [`setHandleCloseCleanup`](#sethandleclosecleanup) `inline` | Registers a cleanup callback that runs when `handle` finally closes. |
| `void` | [`clearHandleCloseCleanup`](#clearhandleclosecleanup) `inline` | Clears any pending close-time cleanup callback registered on `handle`. |
| `auto` | [`withHandleContext`](#withhandlecontext) `inline` | Wraps `callback` so it only runs while the owning handle is still alive. Captures the intrusive [`Context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Context.md#context-2) token, rehydrates the typed owner on entry, and suppresses invocation if the handle has already been deleted. |
| `T &` | [`createRequest`](#createrequest) `inline` | Allocate a heap-owned [`Request`](https://auscaster.com/icey/docs/api-reference/icy-uv-Request.md#request-2) of type `T` and attach `callback` to it. |
| `T &` | [`createRetainedRequest`](#createretainedrequest) `inline` | Allocate a heap-owned [`Request`](https://auscaster.com/icey/docs/api-reference/icy-uv-Request.md#request-2) of type `T` whose callback retains additional state until completion. |

---

<a id="defaultloop"></a>

### defaultLoop

`inline`

```cpp
inline Loop * defaultLoop()
```

[Defined in src/base/include/icy/loop.h:34](https://github.com/auscaster/icey/blob/main/src/base/include/icy/loop.h#L34)

Returns the process-wide default libuv event loop. 
#### Returns
Pointer to the default `uv_loop_t`.

---

<a id="runloop"></a>

### runLoop

`inline`

```cpp
inline void runLoop(Loop * loop = defaultLoop(), uv_run_mode mode = UV_RUN_DEFAULT) = default
```

[Defined in src/base/include/icy/loop.h:43](https://github.com/auscaster/icey/blob/main/src/base/include/icy/loop.h#L43)

Runs the given event loop using the specified run mode. Blocks until the loop exits (when using `UV_RUN_DEFAULT`).

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `loop` | [`Loop`](#loop-1) * | Event loop to run. Defaults to the default loop. |
| `mode` | `uv_run_mode` | libuv run mode: `UV_RUN_DEFAULT`, `UV_RUN_ONCE`, or `UV_RUN_NOWAIT`. |

---

<a id="stoploop"></a>

### stopLoop

`inline`

```cpp
inline void stopLoop(Loop * loop = defaultLoop()) = default
```

[Defined in src/base/include/icy/loop.h:50](https://github.com/auscaster/icey/blob/main/src/base/include/icy/loop.h#L50)

Stops the given event loop, causing `uv_run` to return after the current iteration.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `loop` | [`Loop`](#loop-1) * | Event loop to stop. Defaults to the default loop. |

---

<a id="createloop"></a>

### createLoop

`inline`

```cpp
inline Loop * createLoop()
```

[Defined in src/base/include/icy/loop.h:58](https://github.com/auscaster/icey/blob/main/src/base/include/icy/loop.h#L58)

Allocates and initializes a new libuv event loop. The caller is responsible for closing and deleting the returned loop. 
#### Returns
Pointer to a newly initialized `uv_loop_t`.

---

<a id="closeloop"></a>

### closeLoop

`inline`

```cpp
inline bool closeLoop(Loop * loop)
```

[Defined in src/base/include/icy/loop.h:69](https://github.com/auscaster/icey/blob/main/src/base/include/icy/loop.h#L69)

Closes the given event loop, releasing internal resources. All handles must be closed before calling this. 
#### Returns
True on success, false if the loop still has active handles.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `loop` | [`Loop`](#loop-1) * | Event loop to close. |

---

<a id="handlestorage"></a>

### handleStorage

`inline`

```cpp
template<typename T> inline HandleStorage< T > * handleStorage(T * handle)
```

[Defined in src/base/include/icy/handle.h:53](https://github.com/auscaster/icey/blob/main/src/base/include/icy/handle.h#L53)

Returns the extended storage wrapper that owns `handle`.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `handle` | `T *` | Raw `libuv` handle pointer previously allocated by `Context<T>`. |

---

<a id="sethandleclosecleanup"></a>

### setHandleCloseCleanup

`inline`

```cpp
template<typename T> inline void setHandleCloseCleanup(T * handle, void * data, void(*)(void *) cleanup)
```

[Defined in src/base/include/icy/handle.h:64](https://github.com/auscaster/icey/blob/main/src/base/include/icy/handle.h#L64)

Registers a cleanup callback that runs when `handle` finally closes.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `handle` | `T *` | Raw `libuv` handle pointer. |
| `data` | `void *` | User data passed back to `cleanup`. |
| `cleanup` | `void(*)(void *)` | Function invoked exactly once when the handle storage is released. |

---

<a id="clearhandleclosecleanup"></a>

### clearHandleCloseCleanup

`inline`

```cpp
template<typename T> inline void clearHandleCloseCleanup(T * handle)
```

[Defined in src/base/include/icy/handle.h:75](https://github.com/auscaster/icey/blob/main/src/base/include/icy/handle.h#L75)

Clears any pending close-time cleanup callback registered on `handle`.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `handle` | `T *` | Raw `libuv` handle pointer. |

---

<a id="withhandlecontext"></a>

### withHandleContext

`inline`

```cpp
template<typename Owner, typename Callback> inline auto withHandleContext(Owner & owner, Callback && callback)
```

[Defined in src/base/include/icy/handle.h:469](https://github.com/auscaster/icey/blob/main/src/base/include/icy/handle.h#L469)

Wraps `callback` so it only runs while the owning handle is still alive. Captures the intrusive [`Context`](https://auscaster.com/icey/docs/api-reference/icy-uv-Context.md#context-2) token, rehydrates the typed owner on entry, and suppresses invocation if the handle has already been deleted.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `owner` | `Owner &` | Owning handle instance. |
| `callback` | `Callback &&` | Callable that receives `Owner&` followed by the libuv callback args. |

---

<a id="createrequest"></a>

### createRequest

`inline`

```cpp
template<typename T> inline T & createRequest(std::function< void(const typename T::Event &)> callback)
```

[Defined in src/base/include/icy/request.h:114](https://github.com/auscaster/icey/blob/main/src/base/include/icy/request.h#L114)

Allocate a heap-owned [`Request`](https://auscaster.com/icey/docs/api-reference/icy-uv-Request.md#request-2) of type `T` and attach `callback` to it.

The returned reference is valid until the request's `defaultCallback` fires and deletes the object.

#### Returns
Reference to the newly allocated request.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `callback` | `std::function< void(const typename T::Event &)>` | Completion handler; receives a `T::Event` on completion. |

---

<a id="createretainedrequest"></a>

### createRetainedRequest

`inline`

```cpp
template<typename T, typename Retained, typename Callback> inline T & createRetainedRequest(Retained && retained, Callback && callback)
```

[Defined in src/base/include/icy/request.h:135](https://github.com/auscaster/icey/blob/main/src/base/include/icy/request.h#L135)

Allocate a heap-owned [`Request`](https://auscaster.com/icey/docs/api-reference/icy-uv-Request.md#request-2) of type `T` whose callback retains additional state until completion.

This is the standard way to bind request completion to handle lifetime or other retained context without hand-rolling per-call capture logic.

#### Returns
Reference to the newly allocated request.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `retained` | [`Retained`](https://auscaster.com/icey/docs/api-reference/base.md#packetretention) && | Extra state to keep alive until the request completes. |
| `callback` | `Callback &&` | Completion handler receiving the retained state and event. |