> For the complete documentation index, see [llms.txt](https://harsh-mishra.gitbook.io/pychanio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://harsh-mishra.gitbook.io/pychanio/getting-started/readme.md).

# Getting Started

Welcome to **pychanio**, a concurrency library that brings Go-style channels and `select` semantics to Python's `asyncio` world.

This guide will help you get started with the core concepts, installation steps, and writing your first channel-based program in Python. Whether you're familiar with Go or completely new to channel-based concurrency, this guide aims to make `pychanio` accessible and intuitive.

***

## What is `pychanio`?

`pychanio` is a Python library designed to mimic Go's concurrency primitives:

* **Channels** for coroutine-safe communication
* **Goroutines** via `go(...)`
* **`select` blocks** for non-deterministic choice across multiple awaitables
* **Nil channels** that block forever
* **Sentinels** like `DONE`, `CANCEL`, and `HEARTBEAT` for control flow

With `pychanio`, you can write concurrent code that is expressive, safe, and idiomatic-leveraging Python's `asyncio` without callbacks or tangled task management.

***

## Why use `pychanio`?

Python's built-in `asyncio.Queue` is powerful but lacks Go-style channel semantics:

* **Explicit closing** of queues
* **Backpressure via blocking sends**
* **Separate send-only and receive-only views**
* **Composable `select` blocks**

`pychanio` builds on top of `asyncio` to provide:

* Go-like concurrency in idiomatic Python
* Simplified coordination between producers and consumers
* Clearer patterns for cancellation and shutdown

***

## Core Concepts

Fundamental operations with `pychanio`:

| Operation            | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `chan()`             | Creates a full-duplex channel (buffered/unbuffered)             |
| `ch << val`          | Asynchronously sends `val` into the channel                     |
| `await ch.send()`    | Synchronously sends `val` into the channel                      |
| `await ch.receive()` | Receives a value from the channel                               |
| `await (ch >> None)` | Receives a value from the channel (DSL Syntax)                  |
| `go(fn)`             | Spawns a coroutine in the background (like Go's `go fn()`)      |
| `select(...)`        | Waits on multiple channels and executes the first ready handler |
| `nil()`              | Creates a channel that blocks on all operations                 |

***

## When to Use It

Use `pychanio` when:

* You're coordinating multiple async producers/consumers
* You need fine-grained backpressure control
* You want to fan-in or fan-out data across tasks
* You want readable, Go-inspired concurrency in Python

Don't use it when:

* You need multiprocessing or inter-process communication
* You’re already using threading primitives (e.g., `queue.Queue`)

***

## Next Chapter

In the next chapter, we'll walk through how to install `pychanio` and verify your environment is ready to write concurrent code using channels.