coverage_reservations
coverage_reservations
#
Per-user location reservations — spread a crowd across a survey area.
The spatial sibling of
ReservationBook:
each user leases a place out of a batch, and a place is retired once a capture
lands within threshold of it. area_batch draws a batch from a survey
area: the places farthest from every capture so far.
DEFAULT_LEASE = timedelta(minutes=30)
module-attribute
#
How long a handout is held before, absent a covering capture, it recycles.
CoverageBook
#
Bases: ImpureState
The persistent book of location leases.
batch holds the un-handed-out survey locations; held maps each user
to their [Lease][]. The struct IS the format: changing its shape starts a
fresh book (no migration).
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/organize/coverage_reservations.py
36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 | |
release(user_id)
#
Drop this user's hold, without returning its location to the batch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_id
|
str
|
The user giving up their location. |
required |
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/organize/coverage_reservations.py
reserve(user_id, *, distance, at=None, fulfilled_by=(), threshold=1.0, lease=DEFAULT_LEASE, refill=None, now=None)
#
The location this user holds, leasing one from the batch if none.
@cgserver.intercept(Survey, lambda s: s._metadata._location)
def next_spot(profile: cgserver.RequestProfile, target: Survey) -> cg.Location | None:
covered = target.sessions.values().location
return cgr.scheduling.CoverageBook.open("survey").reserve(
profile.user_id,
at=profile.location,
fulfilled_by=covered,
distance=cgr.scheduling.distance.location(sigma_m=10.0),
refill=cgr.scheduling.area_batch(BOUNDARY, covered),
)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
user_id
|
str
|
The user asking for a location. |
required |
distance
|
Callable[[Location, Location], float]
|
A distance between two |
required |
at
|
Location | None
|
The requester's current location, if known. The batch location closest to it is leased; without it, the batch is leased in insertion order (FIFO). |
None
|
fulfilled_by
|
Iterable[Location | MissingType | None]
|
Captured locations; a reservation or batch location within
|
()
|
threshold
|
float
|
A reservation is released once a capture lies within this
distance of it, in the units |
1.0
|
lease
|
timedelta
|
How long a handout is held before, absent a covering capture, the location returns to the batch. Defaults to 30 minutes. |
DEFAULT_LEASE
|
refill
|
Iterable[Location] | None
|
Locations to install as the batch when it is exhausted,
such as |
None
|
now
|
datetime | None
|
The reference time; defaults to |
None
|
Returns:
| Type | Description |
|---|---|
Location | None
|
The user's reserved location, or |
Location | None
|
and the user holds nothing. |
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/organize/coverage_reservations.py
Lease
#
Bases: Struct
One user's held location and when the hold expires.
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/organize/coverage_reservations.py
area_batch(area, covered, batch=8, spacing_m=2.0)
#
batch places inside area, each far from covered and from each other.
Memoized on its arguments, so a reservation interceptor can pass it as
refill= on every request and draw anew only when a capture lands.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
area
|
Array[Location]
|
The survey boundary, a polygon of at least three places. |
required |
covered
|
Array[Location]
|
The places already captured; absent entries are skipped. |
required |
batch
|
int
|
How many places to pick. |
8
|
spacing_m
|
float
|
The grid spacing inside |
2.0
|
Returns:
| Type | Description |
|---|---|
Array[Location]
|
The picked places; their order is the grid's. |