lustre/utils/hostlist.h

   1 /*****************************************************************************\
   2  *  $Id: hostlist.h,v 1.1.10.2 2008/12/18 18:02:14 johann Exp $
   3  *****************************************************************************
   4  *  Copyright (C) 2002 The Regents of the University of California.
   5  *  Produced at Lawrence Livermore National Laboratory (cf, DISCLAIMER).
   6  *  Written by Mark Grondona <mgrondona@llnl.gov>
   7  *  UCRL-CODE-2002-040.
   8  *
   9  *  This file is part of SLURM, a resource management program.
  10  *  For details, see <http://www.llnl.gov/linux/slurm/>.
  11  *
  12  *  SLURM is free software; you can redistribute it and/or modify it under
  13  *  the terms of the GNU General Public License as published by the Free
  14  *  Software Foundation; either version 2 of the License, or (at your option)
  15  *  any later version.
  16  *
  17  *  SLURM is distributed in the hope that it will be useful, but WITHOUT ANY
  18  *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  19  *  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  20  *  details.
  21  *
  22  *  You should have received a copy of the GNU General Public License along
  23  *  with SLURM; if not, write to the Free Software Foundation, Inc.,
  24  *  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
  25 \*****************************************************************************/
  26
  27 #ifndef _HOSTLIST_H
  28 #define _HOSTLIST_H
  29
  30 /* Notes:
  31  *
  32  * If WITH_LSD_FATAL_ERROR_FUNC is defined, the linker will expect to
  33  * find and external lsd_fatal_error(file,line,mesg) function. By default,
  34  * lsd_fatal_error(file,line,mesg) is a macro definition that outputs an
  35  * error message to stderr. This macro may be redefined to invoke another
  36  * routine instead. e.g.:
  37  *
  38  *    #define lsd_fatal_error(file,line,mesg)  \
  39  *              error("%s:%s %s\n",file,line,mesg);
  40  *
  41  * If WITH_LSD_NOMEM_ERROR_FUNC is defined, the linker will expect to
  42  * find an external lsd_nomem_error(file,line,mesg) function. By default,
  43  * lsd_nomem_error(file,line,mesg) is a macro definition that returns NULL.
  44  * This macro may be redefined to invoke another routine instead.
  45  *
  46  * If WITH_PTHREADS is defined, these routines will be thread-safe.
  47  *
  48  */
  49
  50 /* The hostlist opaque data type
  51  *
  52  * A hostlist is a list of hostnames optimized for a prefixXXXX style
  53  * naming convention, where XXXX  is a decimal, numeric suffix.
  54  */
  55 typedef struct hostlist * hostlist_t;
  56
  57 /* A hostset is a special case of a hostlist. It:
  58  *
  59  * 1. never contains duplicates
  60  * 2. is always sorted
  61  *    (Note: sort occurs first on alphanumeric prefix -- where prefix
  62  *     matches, numeric suffixes will be sorted *by value*)
  63  */
  64 typedef struct hostset * hostset_t;
  65
  66 /* The hostlist iterator type (may be used with a hostset as well)
  67  * used for non-destructive access to hostlist members.
  68  *
  69  */
  70 typedef struct hostlist_iterator * hostlist_iterator_t;
  71
  72 /* ----[ hostlist_t functions: ]---- */
  73
  74 /* ----[ hostlist creation and destruction ]---- */
  75
  76 /*
  77  * hostlist_create():
  78  *
  79  * Create a new hostlist from a string representation.
  80  *
  81  * The string representation (str) may contain one or more hostnames or
  82  * bracketed hostlists separated by either `,' or whitespace. A bracketed
  83  * hostlist is denoted by a common prefix followed by a list of numeric
  84  * ranges contained within brackets: e.g. "tux[0-5,12,20-25]"
  85  *
  86  * Note: if this module is compiled with WANT_RECKLESS_HOSTRANGE_EXPANSION
  87  * defined, a much more loose interpretation of host ranges is used.
  88  * Reckless hostrange expansion allows all of the following (in addition to
  89  * bracketed hostlists):
  90  *
  91  *  o tux0-5,tux12,tux20-25
  92  *  o tux0-tux5,tux12,tux20-tux25
  93  *  o tux0-5,12,20-25
  94  *
  95  * If str is NULL, and empty hostlist is created and returned.
  96  *
  97  * If the create fails, hostlist_create() returns NULL.
  98  *
  99  * The returned hostlist must be freed with hostlist_destroy()
 100  *
 101  */
 102 hostlist_t hostlist_create(const char *hostlist);
 103
 104 /* hostlist_copy():
 105  *
 106  * Allocate a copy of a hostlist object. Returned hostlist must be freed
 107  * with hostlist_destroy.
 108  */
 109 hostlist_t hostlist_copy(const hostlist_t hl);
 110
 111 /* hostlist_destroy():
 112  *
 113  * Destroy a hostlist object. Frees all memory allocated to the hostlist.
 114  */
 115 void hostlist_destroy(hostlist_t hl);
 116
 117
 118 /* ----[ hostlist list operations ]---- */
 119
 120 /* hostlist_push():
 121  *
 122  * push a string representation of hostnames onto a hostlist.
 123  *
 124  * The hosts argument may take the same form as in hostlist_create()
 125  *
 126  * Returns the number of hostnames inserted into the list,
 127  * or 0 on failure.
 128  */
 129 int hostlist_push(hostlist_t hl, const char *hosts);
 130
 131
 132 /* hostlist_push_host():
 133  *
 134  * Push a single host onto the hostlist hl.
 135  * This function is more efficient than hostlist_push() for a single
 136  * hostname, since the argument does not need to be checked for ranges.
 137  *
 138  * return value is 1 for success, 0 for failure.
 139  */
 140 int hostlist_push_host(hostlist_t hl, const char *host);
 141
 142
 143 /* hostlist_push_list():
 144  *
 145  * Push a hostlist (hl2) onto another list (hl1)
 146  *
 147  * Returns 1 for success, 0 for failure.
 148  *
 149  */
 150 int hostlist_push_list(hostlist_t hl1, hostlist_t hl2);
 151
 152
 153 /* hostlist_pop():
 154  *
 155  * Returns the string representation of the last host pushed onto the list
 156  * or NULL if hostlist is empty or there was an error allocating memory.
 157  * The host is removed from the hostlist.
 158  *
 159  * Note: Caller is responsible for freeing the returned memory.
 160  */
 161 char * hostlist_pop(hostlist_t hl);
 162
 163
 164 char * hostlist_nth(hostlist_t hl, int n);
 165
 166 /* hostlist_shift():
 167  *
 168  * Returns the string representation of the first host in the hostlist
 169  * or NULL if the hostlist is empty or there was an error allocating memory.
 170  * The host is removed from the hostlist.
 171  *
 172  * Note: Caller is responsible for freeing the returned memory.
 173  */
 174 char * hostlist_shift(hostlist_t hl);
 175
 176
 177 /* hostlist_pop_range():
 178  *
 179  * Pop the last bracketed list of hosts of the hostlist hl.
 180  * Returns the string representation in bracketed list form.
 181  * All hosts associated with the returned list are removed
 182  * from hl.
 183  *
 184  * Caller is responsible for freeing returned memory
 185  */
 186 char * hostlist_pop_range(hostlist_t hl);
 187
 188 /* hostlist_shift_range():
 189  *
 190  * Shift the first bracketed hostlist (improperly: range) off the
 191  * hostlist hl. Returns the string representation in bracketed list
 192  * form. All hosts associated with the list are removed from the
 193  * hostlist.
 194  *
 195  * Caller is responsible for freeing returned memory.
 196  */
 197 char * hostlist_shift_range(hostlist_t hl);
 198
 199
 200 /* hostlist_find():
 201  *
 202  * Searches hostlist hl for the first host matching hostname
 203  * and returns position in list if found.
 204  *
 205  * Returns -1 if host is not found.
 206  *
 207  */
 208 int hostlist_find(hostlist_t hl, const char *hostname);
 209
 210 /* hostlist_delete():
 211  *
 212  * Deletes all hosts in the list represented by `hosts'
 213  *
 214  * Returns the number of hosts successfully deleted
 215  */
 216 int hostlist_delete(hostlist_t hl, const char *hosts);
 217
 218
 219 /* hostlist_delete_host():
 220  *
 221  * Deletes the first host that matches `hostname' from the hostlist hl.
 222  * Note: "hostname" argument cannot contain a range of hosts
 223  *       (see hostlist_delete() for this functionality.)
 224  *
 225  * Returns 1 if successful, 0 if hostname is not found in list.
 226  */
 227 int hostlist_delete_host(hostlist_t hl, const char *hostname);
 228
 229
 230 /* hostlist_delete_nth():
 231  *
 232  * Deletes the host from position n in the hostlist.
 233  *
 234  * Returns 1 if successful 0 on error.
 235  *
 236  */
 237 int hostlist_delete_nth(hostlist_t hl, int n);
 238
 239
 240 /* hostlist_count():
 241  *
 242  * Return the number of hosts in hostlist hl.
 243  */
 244 int hostlist_count(hostlist_t hl);
 245
 246 /* hostlist_is_empty(): return true if hostlist is empty. */
 247 #define hostlist_is_empty(__hl) ( hostlist_count(__hl) == 0 )
 248
 249 /* ----[ Other hostlist operations ]---- */
 250
 251 /* hostlist_sort():
 252  *
 253  * Sort the hostlist hl.
 254  *
 255  */
 256 void hostlist_sort(hostlist_t hl);
 257
 258 /* hostlist_uniq():
 259  *
 260  * Sort the hostlist hl and remove duplicate entries.
 261  *
 262  */
 263 void hostlist_uniq(hostlist_t hl);
 264
 265
 266 /* ----[ hostlist print functions ]---- */
 267
 268 /* hostlist_ranged_string():
 269  *
 270  * Write the string representation of the hostlist hl into buf,
 271  * writing at most n chars. Returns the number of bytes written,
 272  * or -1 if truncation occurred.
 273  *
 274  * The result will be NULL terminated.
 275  *
 276  * hostlist_ranged_string() will write a bracketed hostlist representation
 277  * where possible.
 278  */
 279 size_t hostlist_ranged_string(hostlist_t hl, size_t n, char *buf);
 280 size_t hostset_ranged_string(hostset_t hs, size_t n, char *buf);
 281
 282 /* hostlist_deranged_string():
 283  *
 284  * Writes the string representation of the hostlist hl into buf,
 285  * writing at most n chars. Returns the number of bytes written,
 286  * or -1 if truncation occurred.
 287  *
 288  * hostlist_deranged_string() will not attempt to write a bracketed
 289  * hostlist representation. Every hostname will be explicitly written.
 290  */
 291 size_t hostlist_deranged_string(hostlist_t hl, size_t n, char *buf);
 292 size_t hostset_deranged_string(hostset_t hs, size_t n, char *buf);
 293
 294
 295 /* ----[ hostlist utility functions ]---- */
 296
 297
 298 /* hostlist_nranges():
 299  *
 300  * Return the number of ranges currently held in hostlist hl.
 301  */
 302 int hostlist_nranges(hostlist_t hl);
 303
 304
 305 /* ----[ hostlist iterator functions ]---- */
 306
 307 /* hostlist_iterator_create():
 308  *
 309  * Creates and returns a hostlist iterator used for non destructive
 310  * access to a hostlist or hostset. Returns NULL on failure.
 311  */
 312 hostlist_iterator_t hostlist_iterator_create(hostlist_t hl);
 313
 314 /* hostset_iterator_create():
 315  *
 316  * Same as hostlist_iterator_create(), but creates a hostlist_iterator
 317  * from a hostset.
 318  */
 319 hostlist_iterator_t hostset_iterator_create(hostset_t set);
 320
 321 /* hostlist_iterator_destroy():
 322  *
 323  * Destroys a hostlist iterator.
 324  */
 325 void hostlist_iterator_destroy(hostlist_iterator_t i);
 326
 327 /* hostlist_iterator_reset():
 328  *
 329  * Reset an iterator to the beginning of the list.
 330  */
 331 void hostlist_iterator_reset(hostlist_iterator_t i);
 332
 333 /* hostlist_next():
 334  *
 335  * Returns a pointer to the  next hostname on the hostlist
 336  * or NULL at the end of the list
 337  *
 338  * The caller is responsible for freeing the returned memory.
 339  */
 340 char * hostlist_next(hostlist_iterator_t i);
 341
 342
 343 /* hostlist_next_range():
 344  *
 345  * Returns the next bracketed hostlist or NULL if the iterator i is
 346  * at the end of the list.
 347  *
 348  * The caller is responsible for freeing the returned memory.
 349  *
 350  */
 351 char * hostlist_next_range(hostlist_iterator_t i);
 352
 353
 354 /* hostlist_remove():
 355  * Removes the last host returned by hostlist iterator i
 356  *
 357  * Returns 1 for success, 0 for failure.
 358  */
 359 int hostlist_remove(hostlist_iterator_t i);
 360
 361
 362 /* ----[ hostset operations ]---- */
 363
 364 /* hostset_create():
 365  *
 366  * Create a new hostset object from a string representation of a list of
 367  * hosts. See hostlist_create() for valid hostlist forms.
 368  */
 369 hostset_t hostset_create(const char *hostlist);
 370
 371 /* hostset_copy():
 372  *
 373  * Copy a hostset object. Returned set must be freed with hostset_destroy().
 374  */
 375 hostset_t hostset_copy(hostset_t set);
 376
 377 /* hostset_destroy():
 378  */
 379 void hostset_destroy(hostset_t set);
 380
 381 /* hostset_insert():
 382  * Add a host or list of hosts into hostset "set."
 383  *
 384  * Returns number of hosts successfully added to "set"
 385  * (insertion of a duplicate is not considered successful)
 386  */
 387 int hostset_insert(hostset_t set, const char *hosts);
 388
 389 /* hostset_delete():
 390  * Delete a host or list of hosts from hostset "set."
 391  * Returns number of hosts deleted from set.
 392  */
 393 int hostset_delete(hostset_t set, const char *hosts);
 394
 395 /* hostset_within():
 396  * Return 1 if all hosts specified by "hosts" are within the hostset "set"
 397  * Retrun 0 if every host in "hosts" is not in the hostset "set"
 398  */
 399 int hostset_within(hostset_t set, const char *hosts);
 400
 401 /* hostset_shift():
 402  * hostset equivalent to hostlist_shift()
 403  */
 404 char * hostset_shift(hostset_t set);
 405
 406 /* hostset_shift_range():
 407  * hostset eqivalent to hostlist_shift_range()
 408  */
 409 char * hostset_shift_range(hostset_t set);
 410
 411 /* hostset_count():
 412  * Count the number of hosts currently in hostset
 413  */
 414 int hostset_count(hostset_t set);
 415
 416
 417 #endif /* !_HOSTLIST_H */