\" Copyright (c) Open Grid Forum (2012). Some Rights Reserved.
\"
\" This document and translations of it may be copied and furnished to
\" others, and derivative works that comment on or otherwise explain it
\" or assist in its implementation may be prepared, copied, published and
\" distributed, in whole or in part, without restriction of any kind,
\" provided that the above copyright notice and this paragraph are
\" included as references to the derived portions on all such copies and
\" derivative works.  The published OGF document from which such works
\" are derived, however, may not be modified in any way, such as by
\" removing the copyright notice or references to the OGF or other
\" organizations, except as needed for the purpose of developing new or
\" updated OGF documents in conformance with the procedures defined in
\" the OGF Document Process, or as required to translate it into
\" languages other than English. OGF, with the approval of its board, may
\" remove this restriction for inclusion of OGF document content for the
\" purpose of producing standards in cooperation with other international
\" standards bodies.
\"
\" The limited permissions granted above are perpetual and will not be
\" revoked by the OGF or its successors or assignees.
.de M    \" man page reference
\\fI\\$1\\fR\\|(\\$2)\\$3
..
.TH drmaa2_list 3 2012-12-01 
.SH NAME
 \- DRMAA2 list routines
.SH SYNOPSIS
.B #include """drmaa.h"""
.nf
\fBstruct drmaa2_list_s;        /*forward*/
typedef struct drmaa2_list_s *drmaa2_list;
typedef struct drmaa2_list_s *drmaa2_string_list;
typedef struct drmaa2_list_s *drmaa2_j_list;
typedef struct drmaa2_list_s *drmaa2_queueinfo_list;
typedef struct drmaa2_list_s *drmaa2_machineinfo_list;
typedef struct drmaa2_list_s *drmaa2_slotinfo_list;
typedef struct drmaa2_list_s *drmaa2_r_list;

typedef enum drmaa2_listtype {
  DRMAA2_STRINGLIST,        
  DRMAA2_JOBLIST,
  DRMAA2_QUEUEINFOLIST,
  DRMAA2_MACHINEINFOLIST,
  DRMAA2_SLOTINFOLIST,
  DRMAA2_RESERVATIONLIST
} drmaa2_listtype;\fP

.BI "typedef void (*drmaa2_list_entryfree)(void **" value ");"
.BI "drmaa2_list drmaa2_list_create (const drmaa2_listtype " t ", const drmaa2_list_entryfree " callback ");"
.BI "void drmaa2_list_free(drmaa2_list *" l ");" 
.BI "const void *drmaa2_list_get(const drmaa2_list " l ", long " pos ");"
.BI "drmaa2_error drmaa2_list_add(drmaa2_list " l ", const void *" value ");"
.BI "drmaa2_error drmaa2_list_del(drmaa2_list " l ", long " pos ");"
.BI "long drmaa2_list_size(const drmaa2_list " l ");"
.fi
.SH DESCRIPTION
.TP
.BR drmaa2_list_create ()
Creates a new list instance for the specified type of items. Returns a
pointer to the list or NULL on error.  Optional parameter
.I callback
allows the application to provide a callback pointer to a collection
element cleanup function.
.B DRMAA2_UNSET_CALLBACK
may be supplied instead of a valid callback pointer.
.TP
.BR drmaa2_list_free ()
Frees the list and the contained members. If a callback function was
provided on list creation, it SHALL be called once per list item.
.TP
.BR drmaa2_list_get ()
Gets the list element at the indicated position. The element index
starts at zero. If the index is invalid, the function returns NULL.
.TP
.BR drmaa2_list_add ()
Adds a new item at the end of the list and returns a success
indication. The list MUST contain only the provided pointer, not a
deep copy of the provided data structure.
.TP
.BR drmaa2_list_del ()
Removes the list element at the indicated position and returns a
success indication. If a callback function was provided on list
creation, it SHALL be called before this function returns.
.TP
.BR drmaa2_list_size ()
Returns the number of elements in the list. If the list is empty, then
the function returns 0, which SHALL NOT be treated as an error case.
.SH "SEE ALSO"
.M drmaa2 3 ,
.M drmaa2_dict 3