usr/src/man/man3dat/dat_ia_close.3dat

   1 '\" te
   2 .\" This manual page is derived from the DAT/uDAPL 1.2 specification.
   3 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DAT_IA_CLOSE 3DAT "Jul 16, 2004"
   8 .SH NAME
   9 dat_ia_close \- close an IA
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
  14 #include <\fBdat/udat.h\fR>
  15
  16 DAT_RETURN
  17     dat_ia_close (
  18     IN    DAT_IA_HANDLE    \fIia_handle\fR,
  19     IN    DAT_CLOSE_FLAGS  \fIia_flags\fR
  20     )
  21 .fi
  22
  23 .SH PARAMETERS
  24 .sp
  25 .ne 2
  26 .na
  27 \fB\fIia_handle\fR\fR
  28 .ad
  29 .RS 13n
  30 Handle for an instance of a DAT IA.
  31 .RE
  32
  33 .sp
  34 .ne 2
  35 .na
  36 \fB\fIia_flags\fR\fR
  37 .ad
  38 .RS 13n
  39 Flags for IA closure. Flag definitions are:
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fBDAT_CLOSE_ABRUPT_FLAG\fR\fR
  44 .ad
  45 .RS 27n
  46 Abrupt close. Abrupt cascading close of IA including all Consumer created DAT
  47 objects.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBDAT_CLOSE_GRACEFUL_FLAG\fR\fR
  54 .ad
  55 .RS 27n
  56 Graceful close. Closure is successful only if all DAT objects created by the
  57 Consumer have been freed before the graceful closure call.
  58 .RE
  59
  60 Default value of \fBDAT_CLOSE_DEFAULT\fR = \fBDAT_CLOSE_ABRUPT_FLAG\fR
  61 represents abrupt closure of IA.
  62 .RE
  63
  64 .SH DESCRIPTION
  65 .sp
  66 .LP
  67 The \fBdat_ia_close()\fR function closes an IA (destroys an instance of the
  68 Interface Adapter).
  69 .sp
  70 .LP
  71 The\fI ia_flags\fR specify whether the Consumer wants abrupt or graceful close.
  72 .sp
  73 .LP
  74 The abrupt close does a phased, cascading destroy. All DAT Objects associated
  75 with an IA instance are destroyed. These include all the connection oriented
  76 Objects: public and reserved Service Points; Endpoints, Connection Requests,
  77 LMRs (including lmr_contexts), RMRs (including rmr_contexts), Event
  78 Dispatchers, CNOs, and Protection Zones. All the waiters on all CNOs, including
  79 the OS Wait Proxy Agents, are unblocked with the DAT_HANDLE_NULL handle returns
  80 for an unblocking EVD. All direct waiters on all EVDs are also unblocked and
  81 return with DAT_ABORT.
  82 .sp
  83 .LP
  84 The graceful close does a destroy only if the Consumer has done a cleanup of
  85 all DAT objects created by the Consumer with the exception of the asynchronous
  86 EVD. Otherwise, the operation does not destroy the IA instance and returns the
  87 \fBDAT_INVALID_STATE\fR.
  88 .sp
  89 .LP
  90 If async EVD was created as part of the of \fBdat_ia_open\fR(3DAT),
  91 \fBdat_ia_close()\fR must destroy it. If \fIasync_evd_handle\fR was passed in
  92 by the Consumer at \fBdat_ia_open()\fR, this handle is not destroyed. This is
  93 applicable to both abrupt and graceful \fIia_flags\fR values.
  94 .sp
  95 .LP
  96 Because the Consumer did not create async EVD explicitly, the Consumer does not
  97 need to destroy it for graceful close to succeed.
  98 .SH RETURN VALUES
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBDAT_SUCCESS\fR\fR
 103 .ad
 104 .RS 30n
 105 The operation was successful.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
 112 .ad
 113 .RS 30n
 114 The operation failed due to resource limitations. This is a catastrophic error.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBDAT_INVALID_HANDLE\fR\fR
 121 .ad
 122 .RS 30n
 123 Invalid DAT handle; \fIia_handle\fR is invalid.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBDAT_INVALID_PARAMETER\fR\fR
 130 .ad
 131 .RS 30n
 132 Invalid parameter; \fIia_flags\fR is invalid.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBDAT_INVALID_STATE\fR\fR
 139 .ad
 140 .RS 30n
 141 Parameter in an invalid state. IA instance has Consumer-created objects
 142 associated with it.
 143 .RE
 144
 145 .SH USAGE
 146 .sp
 147 .LP
 148 The \fBdat_ia_close()\fR function is the root cleanup method for the Provider,
 149 and, thus, all Objects.
 150 .sp
 151 .LP
 152 Consumers are advised to explicitly destroy all Objects they created prior to
 153 closing the IA instance, but can use this function to clean up everything
 154 associated with an open instance of IA. This allows the Consumer to clean up in
 155 case of errors.
 156 .sp
 157 .LP
 158 Note that an abrupt close implies destruction of EVDs and CNOs. Just as with
 159 explicit destruction of an EVD or CNO, the Consumer should take care to avoid a
 160 race condition where a Consumer ends up attempting to wait on an EVD or CNO
 161 that has just been deleted.
 162 .sp
 163 .LP
 164 The techniques described in \fBdat_cno_free\fR(3DAT) and
 165 \fBdat_evd_free\fR(3DAT) can be used for these purposes.
 166 .sp
 167 .LP
 168 If the Consumer desires to shut down the IA as quickly as possible, the
 169 Consumer can call dat_ia_close(abrupt) without unblocking CNO and EVD waiters
 170 in an orderly fashion. There is a slight chance that an invalidated DAT handle
 171 will cause a memory fault for a waiter. But this might be an acceptable
 172 behavior, especially if the Consumer is shutting down the process.
 173 .sp
 174 .LP
 175 No provision is made for blocking on event completion or pulling events from
 176 queues.
 177 .sp
 178 .LP
 179 This is the general cleanup and last resort method for Consumer recovery. An
 180 implementation must provide for successful completion under all conditions,
 181 avoiding hidden resource leakage (dangling memory, zombie processes, and so on)
 182 eventually leading to a reboot of the operating system.
 183 .sp
 184 .LP
 185 The \fBdat_ia_close()\fR function deletes all Objects that were created using
 186 the IA handle.
 187 .sp
 188 .LP
 189 The \fBdat_ia_close()\fR function can decrement a reference count for the
 190 Provider Library that is incremented by \fBdat_ia_open()\fR to ensure that the
 191 Provider Library cannot be removed when it is in use by a DAT Consumer.
 192 .SH ATTRIBUTES
 193 .sp
 194 .LP
 195 See \fBattributes\fR(5) for descriptions of the following attributes:
 196 .sp
 197
 198 .sp
 199 .TS
 200 box;
 201 c | c
 202 l | l .
 203 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 204 _
 205 Interface Stability     Standard: uDAPL, 1.1, 1.2
 206 _
 207 MT-Level        Unsafe
 208 .TE
 209
 210 .SH SEE ALSO
 211 .sp
 212 .LP
 213 \fBdat_cno_free\fR(3DAT), \fBdat_evd_free\fR(3DAT), \fBdat_ia_open\fR(3DAT),
 214 \fBlibdat\fR(3LIB), \fBattributes\fR(5)