79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# Object Storage and Indexing System (OSIS) Actor
|
||
|
||
The OSIS Actor is responsible for storing and indexing objects in the system. It implements the actor interface to process jobs in a **blocking, synchronized manner**.
|
||
|
||
## Job Processing Behavior
|
||
|
||
The OSISActor processes jobs sequentially with the following characteristics:
|
||
|
||
- **Blocking Processing**: Each job is processed completely before the next job begins
|
||
- **Synchronized Execution**: Jobs are executed one at a time in the order they are received
|
||
- **No Concurrency**: Unlike async actors, OSIS ensures no parallel job execution
|
||
- **Deterministic Order**: Job completion follows the exact order of job submission
|
||
|
||
This design ensures data consistency and prevents race conditions when performing storage and indexing operations.
|
||
|
||
## Usage
|
||
|
||
```rust
|
||
use actor_osis::{OSISActor, spawn_osis_actor};
|
||
|
||
// Create an OSIS actor with builder pattern
|
||
let actor = OSISActor::builder()
|
||
.db_path("/path/to/database")
|
||
.redis_url("redis://localhost:6379")
|
||
.build()
|
||
.expect("Failed to build OSISActor");
|
||
|
||
// Or spawn directly with convenience function
|
||
let handle = spawn_osis_actor(
|
||
"/path/to/database".to_string(),
|
||
"redis://localhost:6379".to_string(),
|
||
shutdown_rx,
|
||
);
|
||
```
|
||
|
||
## Actor Properties
|
||
|
||
- **Actor ID**: `"osis"` (constant)
|
||
- **Actor Type**: `"OSIS"`
|
||
- **Processing Model**: Sequential, blocking
|
||
- **Script Engine**: Rhai with OSIS-specific DSL extensions
|
||
## Canonical Redis queues and verification
|
||
|
||
The project uses canonical dispatch queues per script type. For OSIS, the work queue is:
|
||
- hero:q:work:type:osis
|
||
|
||
Consumer behavior:
|
||
- The in-repo actor derives ScriptType=OSIS from its actor_id containing "osis" and BLPOPs hero:q:work:type:osis.
|
||
- This repo’s OSIS actor has been updated so its actor_id is "osis", ensuring it consumes the canonical queue.
|
||
|
||
Quick verification (redis-cli):
|
||
- List work queues:
|
||
- KEYS hero:q:work:type:*
|
||
- Check OSIS queue length:
|
||
- LLEN hero:q:work:type:osis
|
||
- Inspect a specific job (replace {job_id} with the printed id):
|
||
- HGET hero:job:{job_id} status
|
||
- HGET hero:job:{job_id} output
|
||
|
||
Run options:
|
||
- Option A: Run the example which spawns the OSIS actor and dispatches jobs to the canonical queue.
|
||
1) Start Redis (if not already): redis-server
|
||
2) In this repo:
|
||
- cargo run --example actor
|
||
3) Observe the console: job IDs will be printed as they are created and dispatched.
|
||
4) In a separate terminal, verify with redis-cli:
|
||
- LLEN hero:q:work:type:osis (will briefly increment, then return to 0 as the actor consumes)
|
||
- HGET hero:job:{job_id} status (should transition to started then finished)
|
||
- HGET hero:job:{job_id} output (should contain the script result)
|
||
|
||
- Option B: Run the standalone actor binary and dispatch from another process that pushes to the canonical type queue.
|
||
1) Start the actor:
|
||
- cargo run --bin actor_osis
|
||
2) From any producer, LPUSH hero:q:work:type:osis {job_id} after persisting the job hash hero:job:{job_id}.
|
||
3) Use the same redis-cli checks above to confirm consumption and completion.
|
||
|
||
Notes:
|
||
- Hash-only result model is the default. The job result is written to hero:job:{job_id}.output and status=finished.
|
||
- Reply queues (hero:q:reply:{job_id}) are optional and not required for OSIS to function. |