[MERGED] osmo-gsm-tester[master]: doc: Resources.find: add API doc + inline comments

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Neels Hofmeyr gerrit-no-reply at lists.osmocom.org
Mon May 8 10:11:52 UTC 2017


Neels Hofmeyr has submitted this change and it was merged.

Change subject: doc: Resources.find: add API doc + inline comments
......................................................................


doc: Resources.find: add API doc + inline comments

Change-Id: Ib6376794e28f8faff82517af99dfb38ab4689ac8
---
M src/osmo_gsm_tester/resource.py
1 file changed, 30 insertions(+), 1 deletion(-)

Approvals:
  Pau Espin Pedrol: Looks good to me, approved
  Jenkins Builder: Verified



diff --git a/src/osmo_gsm_tester/resource.py b/src/osmo_gsm_tester/resource.py
index 87ea551..73bb184 100644
--- a/src/osmo_gsm_tester/resource.py
+++ b/src/osmo_gsm_tester/resource.py
@@ -271,8 +271,35 @@
         return Resources(self).drop(reserved)
 
     def find(self, want, skip_if_marked=None, do_copy=True):
+        '''
+        Pass a dict of resource requirements, e.g.:
+          want = {
+            'bts': [ {'type': 'osmo-bts-sysmo',}, {} ],
+            'modem': [ {'times': 3} ]
+          }
+        This function tries to find a combination from the available resources that
+        matches these requiremens. The returnvalue is a dict (wrapped in a Resources class)
+        that contains the matching resources in the order of 'want' dict: in above
+        example, the returned dict would have a 'bts' list with the first item being
+        a sysmoBTS, the second item being any other available BTS.
+
+        If skip_if_marked is passed, any resource that contains this key is skipped.
+        E.g. if a BTS has the USED_KEY set like
+          reserved_resources = { 'bts' : {..., '_used': True} }
+        then this may be skipped by passing skip_if_marked='_used'
+        (or rather skip_if_marked=USED_KEY).
+
+        If do_copy is True, the returned dict is a deep copy and does not share
+        lists with any other Resources dict.
+
+        If raise_if_missing is False, this will return an empty item for any
+        resource that had no match, instead of immediately raising an exception.
+        '''
         matches = {}
         for key, want_list in sorted(want.items()): # sorted for deterministic test results
+          # here we have a resource of a given type, e.g. 'bts', with a list
+          # containing as many BTSes as the caller wants to reserve/use. Each
+          # list item contains specifics for the particular BTS.
           with log.Origin(want=key):
             my_list = self.get(key)
 
@@ -281,7 +308,9 @@
             # Try to avoid a less constrained item snatching away a resource
             # from a more detailed constrained requirement.
 
-            # first record all matches
+            # first record all matches, so that each requested item has a list
+            # of all available resources that match it. Some resources may
+            # appear for multiple requested items. Store matching indexes.
             all_matches = []
             for want_item in want_list:
                 item_match_list = []

-- 
To view, visit https://gerrit.osmocom.org/2501
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: Ib6376794e28f8faff82517af99dfb38ab4689ac8
Gerrit-PatchSet: 3
Gerrit-Project: osmo-gsm-tester
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Pau Espin Pedrol <pespin at sysmocom.de>



More information about the gerrit-log mailing list