Celery
===

介紹
---
Celery 是 Python 的一種套件，此套件的功能可以非同步(asynchronous)執行任務(tasks) / 工作(jobs) ，這種非同步的作法很常見於 Web Application。舉個例子說明適合使用 Celery 的情況也許會更清楚，假設有一使用者需要透過 Web Application 匯出一份龐大的資料（可能執行時間很長，超過 30 分鐘），在這情況之下，我們也無法要求使用者一直開著該網頁不關，這時候比較好的作法就是利用非同步的方式執行匯出資料的工作，把工作移到背景執行，然後告知使用者工作執行完畢後會透過 Email / 即時通訊軟體通知工作完成，讓使用者可以回來下載資料，如此一來，使用者就不需要一直開著網頁佔用伺服器的連線數，Celery 就是應用在這種非同步執行的情況下。

架構流程圖
---

Celery Application
---
在使用 Celery 時，需要實例化(instantiated) Celery ，這個實例(instance)就被稱為 Application 或者 `app` ，因此可以看到 Celery 文件中通常會用 `app` 來命名。另外，Celery 是 thread-safe 的，所以可以多個 Celery Application 共存。

程式碼

from celery import Celery
app = Celery()

Task
---
Task 是 Celery 執行的最小單位，如果要讓工作可以非同步進行，就得把這些工作切分成一個個 Task 。等於是定義好 Celery Application 提供哪些 Task 被非同步執行。

### 異步任務 (Asynchronous Task)
異步任務是指那些不會阻塞當前程序或者進程的執行的任務。這些任務在背景中運行，允許主程序繼續處理其他事務，而不需要等待異步任務完成。

特點：
- 非阻塞： 主程序發起任務後可以繼續執行，不需等待異步任務完成。
- 背景處理： 任務在背景進行，通常不影響主程序的響應時間。
- 應用場景： 處理需時間的請求、性能密集型或I/O密集型任務等。

### 定時任務 (Scheduled Task)
定時任務指的是那些被設定在特定時間或按照一定時間間隔重複執行的任務。這種任務通常用於需要定期執行的操作，比如數據備份、報告生成、定期檢查系統狀態等。

特點：
- 時間控制： 任務根據預設的時間表自動觸發。
- 周期性： 任務可以設定為一次性的或重複執行（如每日、每週等）。
- 應用場景： 數據備份、自動報告、定期維護作業等。

以下為官方文件中的範例 Task :

@app.task
def add(x, y):
  return x + y

Worker
---
有 Task 之後，就需要有 Process(排程) 負責執行 Task ，這樣才能夠達到非同步執行的目標，這時候就需要 Worker 在背景執行 Task 。所以 Celery 官方文件也提到了啟動 Worker 的指令：

#終端機
celery -A task worker --loglevel=info

Task Message & Broker
---
定義好 Task 與啟動 Worker 之後，要怎麼叫 Worker 執行 Task 呢
這時候就需要靠 Task Message 告訴 Celery Application 要非同步執行某個 Task ， Celery Application 會幫忙找到 Worker 執行 Task 。而 Task Message 本身不會夾帶任何程式碼，只會帶有要執行的 Task 名稱及參數等資訊（如果可以夾帶程式碼就可以執行任意程式碼，造成可怕的安全漏洞）。然而， Celery 並不負責 Task Message 的傳遞，這時候就需要 1 個稱為 Broker 的角色負責傳遞 Task Message ，也因此可以看到 Celery 官方文件提到需要 Broker 。

目前 Celery 支援的 Brokers：
RabbitMQ
Redis
Amazon SQS
Zookeeper

Result Backend
---
如果要追蹤 Task 的執行的狀態（例如 PENDING, STARTED, SUCCESS, FAILURE, RETRY, REVOKED 等狀態，詳見 Built-in States ），就需要 Result Backend 儲存 Task 的狀態，這就是 Result Backend 的作用，所以也可以看到 Celery 文件中提到 Result Backend 的相關設定。

前置動作
---
- 先把 Broker 安裝好, 這邊統一使用 redis, 因為 redis 同時也可作為 cache server 使用，可以讓系統架構單純許多，開發速度也會快一些，安裝步驟請參考最下方的 "參考資料"

安裝
---

# 安裝 Celery 套件
pip install celery

# 安裝 gevent 套件
pip install gevent

程式碼內容
---

// task.py
from celery import Celery

app = Celery(
    'task',
    broker='redis://127.0.0.1:6379', // 我們的 broker
    backend='redis://127.0.0.1:6379/1', // 
)

//Task 內容
@app.task
def add(x, y):
    return x + y

if __name__ == '__main__':
    app.worker_main()

執行
---
先啟動 Celery

# 執行 Celery Worker
celery -A task worker --loglevel=info

創建另一個 py檔, 來使用我們的 Task

// test.py
from task import add

result = add.delay(4, 6)
print(result.get())

結果
---

Flower 監控工具
---

安裝

pip install flower

執行指令

celery -A <your_project_name> flower

利用網址進入頁面

http://localhost:5555/

常用指令
---
| 指令名稱 | 指令功能 |
| :--: | :--: |
| worker | 啟動 worker |
| -A | 指定應用程序名稱 |
| -l {DEBUG/INFO/WARNING/ERROR/CRITICAL/FATAL} | 日誌記錄級別 |
| -S | 狀態資料庫的路徑，檔名可能會附加 '.db' 擴展名 |
| -D | 以背景進程的方式啟動 worker |
| -O {default/fair} | 應用優化設定檔 |
| --prefetch-multiplier {prefetch multiplier} | 為這個 worker 實例設定自定義的預取倍數值 |
| -n {HOSTNAME} | 設定自定義主機名（例如：'w1@%%h'），展開：%%h（主機名），%%n（名稱）和 %%d（域） |
| - -purge | 清除隊列(Broker) |

其他指令 ( 輸入指令 celery worker –help )
---
### Pool Options
| 指令用法 | 指令功能 |
| :--: | :--: |
| -c {concurrency} | 處理隊列的子進程數量 |
| -P {prefork/eventlet/gevent/solo/processes/threads/custom} | 池實現 |
| -E | 發送與任務相關的事件，這些事件可以被像 celery events、celerymon 等監控捕捉到 |
| - -time-limit {FLOAT/INT} | 啟用任務的硬時間限制（以秒為單位的 int/float） |
| - -soft-time-limit {FLOAT/INT} | 啟用任務的軟時間限制（以秒為單位的 int/float） |
| - -max-tasks-per-child {INT} | 一個池工作進程可以執行的最大任務數，在此之後它將被終止並替換為一個新進程 |
| - -max-memory-per-child {INT} | 一個子進程在被替換之前可能消耗的最大常駐內存量（以 KiB 為單位） |

### Queue Options
| 指令用法 | 指令功能 |
| :--: | :--: |
| -Q | 指定隊列列表 |
| -X | 排除隊列列表 |
| -I | 包含隊列列表 |

### Features Options
| 指令用法 | 指令功能 |
| :--: | :--: |
| - -without-gossip | 不啟用 gossip |
| - -without-mingle | 不啟用 mingle |
| - -without-heartbeat | 不發送心跳 |
| - -heartbeat-interval {INT} | 設定心跳間隔（整數） |
| - -autoscale {MIN WORKERS}, {MAX WORKERS} | 自動縮放工作進程數量，從最小到最大 |

### Embedded Beat Options
| 指令用法 | 指令功能 |
| :--: | :--: |
| -B | 啟動嵌入式的 beat |
| -s | 設定時程表的檔案名 |
| - -scheduler {TEXT} | 指定時程表的調度器 |

### Daemonization Options
| 指令用法 | 指令功能 |
| :--: | :--: |
| -f | 日誌文件的儲存位置；預設為標準錯誤 |
| - -pidfile {TEXT} | PID 文件的路徑；預設不使用 PID 文件 |
| - -uid {TEXT} | 降低權限至指定的用戶 ID |
| - -gid {TEXT} | 降低權限至指定的群組 ID |
| - -umask {TEXT} | 以此 umask 創建檔案和目錄 |
| - -executable {TEXT} | 覆蓋 Python 可執行檔的路徑 |

實例化
---
在電腦系統中，任何時候基於某種模型的一個新的東西被建立後，都可以說該模型已經被實例化。這個實例通常與其他基於同一模型的實例有一個共同的資料結構，但儲存在實例中的值是獨立的。這樣，改變一個實例中的值就不會干擾到其他一些實例的值。

在物件導向程式設計中，實例是任何對象的具體實現，建立一個實例被稱為實例化。在類別為基編程中，一個對象就是一個類別的實例，對象由建構函式建立，並由解構函式銷毀。該對象可以稱為類別實例或類對象。並非所有的類都可以被實例化，抽象類就不能被實例化。

參考資料
---

[Broker redis 安裝](https://officeguide.cc/ubuntu-linux-redis-database-installation-configuration-tutorial-examples/) (幫我做到測試資料庫的部分就好)

[Celery](https://officeguide.cc/celery-distributed-task-queue-getting-started-1/)

[Celery2](
https://zoejoyuliao.medium.com/django-celery-redis-gmail-%E5%AF%84%E4%BF%A1-375904d4224c)

[Celery3](https://ithelp.ithome.com.tw/m/articles/10273022)

[Celery4](https://hackmd.io/@aaronlife/python-topic-scheduler)

[Celery5](https://geeeez.github.io/posts/Celery-timing/)