dat_ia_close(3dat)

1dat_ia_close(3DAT) Direct Access Transport Library Functionsdat_ia_close(3DAT)
2
3
4

NAME

6       dat_ia_close - close an IA
7

SYNOPSIS

9       cc [ flag... ] file... -ldat [ library... ]
10       #include <dat/udat.h>
11
12       DAT_RETURN
13           dat_ia_close (
14           IN    DAT_IA_HANDLE    ia_handle,
15           IN    DAT_CLOSE_FLAGS  ia_flags
16           )
17
18

PARAMETERS

20       ia_handle    Handle for an instance of a DAT IA.
21
22
23       ia_flags     Flags for IA closure. Flag definitions are:
24
25                    DAT_CLOSE_ABRUPT_FLAG      Abrupt  close. Abrupt cascading
26                                               close of IA including all  Con‐
27                                               sumer created DAT objects.
28
29
30                    DAT_CLOSE_GRACEFUL_FLAG    Graceful close. Closure is suc‐
31                                               cessful only if all DAT objects
32                                               created  by  the  Consumer have
33                                               been freed before the  graceful
34                                               closure call.
35
36                    Default value of DAT_CLOSE_DEFAULT = DAT_CLOSE_ABRUPT_FLAG
37                    represents abrupt closure of IA.
38
39

DESCRIPTION

41       The dat_ia_close() function closes an IA (destroys an instance  of  the
42       Interface Adapter).
43
44
45       The  ia_flags  specify  whether  the  Consumer wants abrupt or graceful
46       close.
47
48
49       The abrupt close does a phased,  cascading  destroy.  All  DAT  Objects
50       associated  with  an  IA  instance are destroyed. These include all the
51       connection oriented Objects: public and reserved Service  Points;  End‐
52       points,   Connection  Requests,  LMRs  (including  lmr_contexts),  RMRs
53       (including  rmr_contexts),  Event  Dispatchers,  CNOs,  and  Protection
54       Zones. All the waiters on all CNOs, including the OS Wait Proxy Agents,
55       are unblocked with the DAT_HANDLE_NULL handle returns for an unblocking
56       EVD.  All direct waiters on all EVDs are also unblocked and return with
57       DAT_ABORT.
58
59
60       The graceful close does a destroy only  if  the  Consumer  has  done  a
61       cleanup  of  all DAT objects created by the Consumer with the exception
62       of the asynchronous EVD. Otherwise, the operation does not destroy  the
63       IA instance and returns the DAT_INVALID_STATE.
64
65
66       If  async  EVD  was  created  as  part  of  the  of  dat_ia_open(3DAT),
67       dat_ia_close() must destroy it. If async_evd_handle was  passed  in  by
68       the  Consumer  at  dat_ia_open(), this handle is not destroyed. This is
69       applicable to both abrupt and graceful ia_flags values.
70
71
72       Because the Consumer did not create async EVD explicitly, the  Consumer
73       does not need to destroy it for graceful close to succeed.
74

RETURN VALUES

76       DAT_SUCCESS                   The operation was successful.
77
78
79       DAT_INSUFFICIENT_RESOURCES    The operation failed due to resource lim‐
80                                     itations. This is a catastrophic error.
81
82
83       DAT_INVALID_HANDLE            Invalid DAT handle; ia_handle is invalid.
84
85
86       DAT_INVALID_PARAMETER         Invalid parameter; ia_flags is invalid.
87
88
89       DAT_INVALID_STATE             Parameter  in  an   invalid   state.   IA
90                                     instance   has  Consumer-created  objects
91                                     associated with it.
92
93

USAGE

95       The  dat_ia_close()  function  is  the  root  cleanup  method  for  the
96       Provider, and, thus, all Objects.
97
98
99       Consumers  are  advised  to explicitly destroy all Objects they created
100       prior to closing the IA instance, but can use this function to clean up
101       everything associated with an open instance of IA. This allows the Con‐
102       sumer to clean up in case of errors.
103
104
105       Note that an abrupt close implies destruction of EVDs and CNOs. Just as
106       with  explicit  destruction  of an EVD or CNO, the Consumer should take
107       care to avoid a race condition where a Consumer ends up  attempting  to
108       wait on an EVD or CNO that has just been deleted.
109
110
111       The  techniques  described in dat_cno_free(3DAT) and dat_evd_free(3DAT)
112       can be used for these purposes.
113
114
115       If the Consumer desires to shut down the IA as quickly as possible, the
116       Consumer  can  call dat_ia_close(abrupt) without unblocking CNO and EVD
117       waiters in an orderly fashion. There is a slight chance that an invali‐
118       dated DAT handle will cause a memory fault for a waiter. But this might
119       be an acceptable behavior, especially if the Consumer is shutting  down
120       the process.
121
122
123       No provision is made for blocking on event completion or pulling events
124       from queues.
125
126
127       This is the general cleanup and last resort method for Consumer  recov‐
128       ery. An implementation must provide for successful completion under all
129       conditions, avoiding hidden resource leakage (dangling  memory,  zombie
130       processes,  and  so on) eventually leading to a reboot of the operating
131       system.
132
133
134       The dat_ia_close() function deletes all Objects that were created using
135       the IA handle.
136
137
138       The  dat_ia_close()  function  can  decrement a reference count for the
139       Provider Library that is incremented by dat_ia_open()  to  ensure  that
140       the  Provider Library cannot be removed when it is in use by a DAT Con‐
141       sumer.
142

ATTRIBUTES

144       See attributes(5) for descriptions of the following attributes:
145
146
147
148
149       ┌─────────────────────────────┬─────────────────────────────┐
150       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
151       ├─────────────────────────────┼─────────────────────────────┤
152       │Interface Stability          │Standard: uDAPL, 1.1, 1.2    │
153       ├─────────────────────────────┼─────────────────────────────┤
154       │MT-Level                     │Unsafe                       │
155       └─────────────────────────────┴─────────────────────────────┘
156