Model Musings
SimPy FilterStore Explained: Getting Exactly What You Need
- Published
- Reading time
- 5 min
Store gives you the next item. FilterStore lets you be picky.
The Problem Store Can’t Solve
Regular Store is FIFO: first in, first out. But what if you need a specific item?
# With regular Store
store = simpy.Store(env)
store.put({'type': 'red', 'id': 1})
store.put({'type': 'blue', 'id': 2})
store.put({'type': 'red', 'id': 3})
# You can only get item 1, then 2, then 3
# No way to say "give me a blue one"
FilterStore fixes this.
Basic Usage
import simpy
env = simpy.Environment()
store = simpy.FilterStore(env, capacity=10)
# Put some items
yield store.put({'type': 'red', 'value': 1})
yield store.put({'type': 'blue', 'value': 2})
yield store.put({'type': 'red', 'value': 3})
# Get specifically a blue item
blue = yield store.get(lambda x: x['type'] == 'blue')
print(blue) # {'type': 'blue', 'value': 2}
The filter function receives each item and returns True if it matches.
How Filtering Works
When you get() with a filter:
- FilterStore checks each item against your filter
- First matching item is returned
- If no match, the get blocks until a matching item arrives
# Will block until a green item is put
green = yield store.get(lambda x: x['type'] == 'green')
Real-World Example: Parts Bin
import random
import simpy
class Part:
def __init__(self, part_type, size, quality):
self.part_type = part_type
self.size = size
self.quality = quality
def __repr__(self):
return f"Part({self.part_type}, {self.size}, {self.quality:.2f})"
def supplier(env, bin):
"""Delivers random parts."""
types = ['bolt', 'nut', 'washer']
sizes = ['small', 'medium', 'large']
while True:
part = Part(
random.choice(types),
random.choice(sizes),
random.uniform(0.8, 1.0)
)
yield bin.put(part)
yield env.timeout(1)
def assembler(env, bin, needs_type, needs_size):
"""Assembles using specific parts."""
while True:
# Get exactly what we need
part = yield bin.get(
lambda p: p.part_type == needs_type and p.size == needs_size
)
print(f"Got {part} at {env.now}")
yield env.timeout(5) # Assembly time
random.seed(42)
env = simpy.Environment()
parts_bin = simpy.FilterStore(env)
env.process(supplier(env, parts_bin))
env.process(assembler(env, parts_bin, 'bolt', 'medium'))
env.process(assembler(env, parts_bin, 'nut', 'small'))
env.run(until=50)
print(f"Left in the bin: {len(parts_bin.items)} parts")
Output:
Got Part(nut, small, 0.84) at 1
Got Part(nut, small, 0.82) at 11
Got Part(bolt, medium, 0.97) at 12
Got Part(nut, small, 0.91) at 16
Got Part(bolt, medium, 0.86) at 20
Got Part(nut, small, 0.97) at 21
Got Part(nut, small, 0.93) at 26
Got Part(nut, small, 0.93) at 32
Got Part(nut, small, 0.85) at 37
Got Part(bolt, medium, 0.88) at 41
Left in the bin: 40 parts
Each assembler takes only its own part and ignores the rest. Of the 50 parts delivered, ten were wanted; the other 40 (washers, large bolts and the like) are still in the bin. A FilterStore with no capacity never turns them away, and every get() has to look past them, which is the linear search the performance section below warns about.
Multiple Criteria
Combine conditions in the filter:
# Get a large red item
item = yield store.get(
lambda x: x['type'] == 'red' and x['size'] == 'large'
)
# Get any item with value > 10
item = yield store.get(lambda x: x['value'] > 10)
# Get by multiple possible types
item = yield store.get(lambda x: x['type'] in ['red', 'blue'])
Default Get (No Filter)
Without a filter, FilterStore behaves like regular Store:
# Get any item (FIFO)
item = yield store.get()
Checking Available Items
Peek at what’s in the store:
# All items
print(store.items)
# Check if any match
matching = [x for x in store.items if x['type'] == 'blue']
print(f"Blue items available: {len(matching)}")
But remember: checking doesn’t reserve. Another process might grab it first.
Non-Blocking Filter Get
What if you don’t want to wait?
def try_get_blue(env, store, timeout):
get_event = store.get(lambda x: x['type'] == 'blue')
timeout_event = env.timeout(timeout)
result = yield get_event | timeout_event
if get_event in result:
return get_event.value
else:
get_event.cancel()
return None
Priority with Filtering
Need priority AND filtering? Combine patterns:
class PrioritizedPart:
def __init__(self, priority, part_type, part_id):
self.priority = priority
self.part_type = part_type
self.part_id = part_id
def get_highest_priority_of_type(store, part_type):
"""Get highest priority item of specific type."""
matching = [p for p in store.items if p.part_type == part_type]
if not matching:
return None
matching.sort(key=lambda x: x.priority)
return matching[0]
# The helper only finds the item; take that very object with a filter
best = get_highest_priority_of_type(store, 'bolt')
if best is not None:
part = yield store.get(lambda p: p is best)
Or use a custom store class.
FilterStore vs PriorityStore
| Feature | FilterStore | PriorityStore |
|---|---|---|
| Selection | By custom filter | By priority |
| Multiple criteria | Yes | No |
| Get any item | Yes | Yes (lowest priority) |
| Complexity | Higher | Lower |
Use FilterStore when selection criteria are complex. Use PriorityStore when you just need ordering.
Example: Taxi Dispatch
import random
import simpy
class Ride:
def __init__(self, pickup, destination, passengers):
self.pickup = pickup
self.destination = destination
self.passengers = passengers
def dispatch_taxi(env, ride_queue, taxi_type, capacity):
"""Taxi only takes rides it can handle."""
while True:
# Only get rides within capacity
ride = yield ride_queue.get(lambda r: r.passengers <= capacity)
print(f"{env.now:3}: {taxi_type} takes ride for {ride.passengers} from {ride.pickup}")
yield env.timeout(10)
random.seed(42)
env = simpy.Environment()
rides = simpy.FilterStore(env)
# Small taxi (up to 4 passengers)
env.process(dispatch_taxi(env, rides, "SmallTaxi", 4))
# Large taxi (up to 7 passengers)
env.process(dispatch_taxi(env, rides, "LargeTaxi", 7))
# Generate rides
def generate_rides(env, queue):
for i in range(8):
ride = Ride(f"Location{i}", f"Dest{i}", random.randint(1, 6))
yield queue.put(ride)
yield env.timeout(2)
env.process(generate_rides(env, rides))
env.run(until=100)
Output:
0: LargeTaxi takes ride for 6 from Location0
2: SmallTaxi takes ride for 1 from Location1
10: LargeTaxi takes ride for 1 from Location2
12: SmallTaxi takes ride for 3 from Location4
20: LargeTaxi takes ride for 6 from Location3
22: SmallTaxi takes ride for 2 from Location5
30: LargeTaxi takes ride for 2 from Location6
32: SmallTaxi takes ride for 2 from Location7
Follow the party of six at Location3. It books at 6. At 10 the large taxi takes the first ride it can handle (a single passenger from Location2), and at 12 the small taxi passes Location3 over for Location4. The six wait until 20. FilterStore hands over the first matching item in the order they were put; if the large taxi should favour large parties, say so in its filter or give large parties a store of their own.
Performance Consideration
FilterStore checks items linearly. With thousands of items, this matters.
For high-performance scenarios:
- Keep stores small
- Use multiple stores by category
- Consider custom data structures
Common Gotchas
Filter Never Matches
# Blocks forever if no blue items ever arrive
blue = yield store.get(lambda x: x['type'] == 'blue')
Add timeouts for safety.
Modifying Items
item = yield store.get(lambda x: x['id'] == 5)
item['status'] = 'processed' # Changes the object
# If you put it back, filters will see the change
yield store.put(item)
Be careful about mutating items.
Summary
FilterStore:
- Lets you get specific items, not just FIFO
- Filter function returns True for matching items
- Blocks until a match is found
- Perfect for typed queues, dispatch systems, inventory
When FIFO isn’t enough, filter.