Parse a user-id pool definition.

Parameters:

• value - string representation of the user-id pool. The accepted input format is a list of integer ranges. The boundaries are inclusive. Example: '1000-5000,8000,9000-9010'.
• separator - the separator character between the uids/uid-ranges. Defaults to a comma.

Returns:

a list of integer pairs (lower, higher range boundaries)

Add a list of user-ids/user-id ranges to a user-id pool.

Parameters:

• uid_pool - a user-id pool (list of integer tuples)
• add_uids - user-id ranges to be added to the pool (list of integer tuples)

Remove a list of user-ids/user-id ranges from a user-id pool.

Parameters:

• uid_pool - a user-id pool (list of integer tuples)
• remove_uids - user-id ranges to be removed from the pool (list of integer tuples)

Convert the internal representation of the user-id pool into a string.

The output format is also accepted by ParseUidPool()

Parameters:

• uid_pool - a list of integer pairs representing UID ranges
• separator - the separator character between the uids/uid-ranges. Defaults to ", ".

Returns:

a string with the formatted results

Sanity check user-id pool range definition values.

Parameters:

• uid_pool - a list of integer pairs (lower, higher range boundaries)

Expands a uid-pool definition to a list of uids.

Parameters:

• uid_pool - a list of integer pairs (lower, higher range boundaries)

Returns:

a list of integers

Tries to find an unused uid from the uid-pool, locks it and returns it.

Usage pattern

1. When starting a process:

      from ganeti import ssconf
      from ganeti import uidpool
   
      # Get list of all user-ids in the uid-pool from ssconf
      ss = ssconf.SimpleStore()
      uid_pool = uidpool.ParseUidPool(ss.GetUidPool(), separator="\n")
      all_uids = set(uidpool.ExpandUidPool(uid_pool))
   
      uid = uidpool.RequestUnusedUid(all_uids)
      try:
        <start a process with the UID>
        # Once the process is started, we can release the file lock
        uid.Unlock()
      except ..., err:
        # Return the UID to the pool
        uidpool.ReleaseUid(uid)
   

2. Stopping a process:

      from ganeti import uidpool
   
      uid = <get the UID the process is running under>
      <stop the process>
      uidpool.ReleaseUid(uid)
   

Parameters:

• all_uids (set of integers) - a set containing all the user-ids in the user-id pool

Returns:

a LockedUid object representing the unused uid. It's the caller's responsibility to unlock the uid once an instance is started with this uid.

This should be called when the given user-id is no longer in use.

Parameters:

• uid (LockedUid or integer) - the uid to release back to the pool

Execute a callable and provide an unused user-id in its kwargs.

This wrapper function provides a simple way to handle the requesting, unlocking and releasing a user-id. "fn" is called by passing a "uid" keyword argument that contains an unused user-id (as an integer) selected from the set of user-ids passed in all_uids. If there is an error while executing "fn", the user-id is returned to the pool.

Parameters:

• fn - a callable that accepts a keyword argument called "uid"
• all_uids (a set of integers) - a set containing all user-ids in the user-id pool