Manual Pages for UNIX Operating System command usage for man dat_evd_dequeue

Direct Access Transport Library Functions   dat_evd_dequeue(3DAT)



NAME
     dat_evd_dequeue - remove the  first  event  from  the  Event
     Dispatcher event queue

SYNOPSIS
     cc [ flag... ] file... -ldat [ library... ]
     #include 

     DAT_RETURN
         dat_evd_dequeue(
         IN    DAT_EVD_HANDLE    evd_handle,
         OUT   DAT_EVENT         *event
         )


PARAMETERS
     evd_handle    Handle  for   an   instance   of   the   Event
                   Dispatcher.


     event         Pointer to  the  Consumer-allocated  structure
                   that Provider fills with the event data.


DESCRIPTION
     The dat_evd_dequeue() function removes the first event  from
     the  Event  Dispatcher  event  queue  and fills the Consumer
     allocated event structure with event data. The first element
     in  this  structure provides the type of the event; the rest
     provides the event-type-specific  parameters.  The  Consumer
     should  allocate  an  event structure big enough to hold any
     event that the Event Dispatcher can deliver.


     For all events the Provider fills  the  dat_event  that  the
     Consumer  allocates.  So  for  all  events,  all  fields  of
     dat_event are OUT from  the  Consumer  point  of  view.  For
     DAT_CONNECTION_REQUEST_EVENT, the Provider creates a Connec-
     tion Request whose cr_handle is returned to the Consumer  in
     DAT_CR_ARRIVAL_EVENT_DATA.  That  object is destroyed by the
     Provider      as      part      of      dat_cr_accept(3DAT),
     dat_cr_reject(3DAT),  or  dat_cr_handoff(3DAT). The Consumer
     should not use cr_handle or any of its parameters, including
     private_data,  after  one  of  these operations destroys the
     Connection Request.


     For DAT_CONNECTION_EVENT_ESTABLISHED for the Active side  of
     connection  establishment,  the Provider returns the pointer
     for private_data and the private_data_size. For the  Passive
     side, DAT_CONNECTION_EVENT_ESTABLISHED event private_data is
     not defined and private_data_size returns zero. The Provider



SunOS 5.11          Last change: 16 Jul 2004                    1






Direct Access Transport Library Functions   dat_evd_dequeue(3DAT)



     is  responsible  for  the memory allocation and deallocation
     for private_data. The private_data is valid until the Active
     side    Consumer    destroys    the    connected    Endpoint
     (dat_ep_free(3DAT)), or transitions the Endpoint into Uncon-
     nected  state  so  it  is  ready for the next connection. So
     while the Endpoint is in Connected, Disconnect  Pending,  or
     Disconnected       state,      the      private_data      of
     DAT_CONNECTION_REQUEST_EVENT is still valid for Active  side
     Consumers.


     Provider must pass to the Consumer the entire  Private  Data
     that  the remote Consumer provided for dat_ep_connect(3DAT),
     dat_ep_dup_connect(3DAT), and dat_cr_accept(). If the Consu-
     mer  provides  more data than the Provider and Transport can
     support (larger than IA Attribute of max_private_data_size),
     DAT_INVALID_PARAMETER is returned for that operation.


     The returned event that was  posted  from  an  Event  Stream
     guarantees  Consumers  that all events that were posted from
     the same Event Stream  prior  to  the  returned  event  were
     already   returned   to   a   Consumer  directly  through  a
     dat_evd_dequeue() or dat_evd_wait(3DAT) operation.


     The ordering of events  dequeued  by  overlapping  calls  to
     dat_evd_wait() or dat_evd_dequeue() is not specified.

RETURN VALUES
     DAT_SUCCESS           The operation was successful. An event
                           was returned to a Consumer.


     DAT_INVALID_HANDLE    Invalid  DAT  handle;  evd_handle   is
                           invalid.


     DAT_QUEUE_EMPTY       There are  no  entries  on  the  Event
                           Dispatcher queue.


     DAT_INVALID_STATE     One of the parameters was invalid  for
                           this  operation.  There  is  already a
                           waiter on the EVD.


USAGE
     No matter how many contexts attempt to dequeue from an Event
     Dispatcher,  each  event is delivered exactly once. However,
     which Consumer receives which event is not defined. The Pro-
     vider is not obligated to provide the first caller the first



SunOS 5.11          Last change: 16 Jul 2004                    2






Direct Access Transport Library Functions   dat_evd_dequeue(3DAT)



     event unless it is the only  caller.  The  Provider  is  not
     obligated  to  ensure  that  the  caller receiving the first
     event executes earlier than contexts receiving later events.


     Preservation of event ordering within an Event Stream is  an
     important feature of the DAT Event Model. Consumers are cau-
     tioned   that   overlapping   or   concurrent    calls    to
     dat_evd_dequeue()  from multiple contexts can undermine this
     ordering information. After multiple contexts are  involved,
     the  Provider  can only guarantee the order that it delivers
     events into the EVD. The Provider cannot guarantee that they
     are processed in the correct order.


     Although calling dat_evd_dequeue() does not cause a  context
     switch,  the Provider is under no obligation to prevent one.
     A context could successfully complete a  dequeue,  and  then
     reach  the end of its timeslice, before returning control to
     the Consumer code. Meanwhile, a context  receiving  a  later
     event could be executing.


     The Event ordering is preserved when dequeueing  is  serial-
     ized.  Potential Consumer serialization methods include, but
     are not limited to, performing all dequeueing from a  single
     context  or  protecting  dequeueing  by way of lock or sema-
     phore.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|
    | Standard                    | uDAPL, 1.1, 1.2             |
    |_____________________________|_____________________________|


SEE ALSO
     dat_cr_accept(3DAT),                   dat_cr_handoff(3DAT),
     dat_cr_reject(3DAT),                   dat_ep_connect(3DAT),
     dat_ep_dup_connect(3DAT),                 dat_ep_free(3DAT),
     dat_evd_wait(3DAT)libdat(3LIB), attributes(5)




SunOS 5.11          Last change: 16 Jul 2004                    3