nm_sendrecv_interface.h

Go to the documentation of this file.

/*
 * NewMadeleine
 * Copyright (C) 2006-2026 (see AUTHORS file)
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 */
 
#ifndef NM_SENDRECV_INTERFACE_H
#define NM_SENDRECV_INTERFACE_H
 
#include <nm_public.h>
#include <nm_session_interface.h>
#include <nm_core_interface.h>
#include <sys/uio.h>
#include <limits.h>
 
NM_EXTERN_C_BEGIN
 
typedef enum
  {
    NM_SR_EVENT_NONE            = 0,
    NM_SR_EVENT_RECV_UNEXPECTED = NM_STATUS_UNEXPECTED,
    NM_SR_EVENT_RECV_COMPLETED  = NM_STATUS_UNPACK_COMPLETED,
    NM_SR_EVENT_SEND_COMPLETED  = NM_STATUS_PACK_COMPLETED,
    NM_SR_EVENT_RECV_DATA       = NM_STATUS_UNPACK_DATA0,
    NM_SR_EVENT_RECV_CANCELLED  = NM_STATUS_UNPACK_CANCELLED,
    NM_SR_EVENT_FINALIZED       = NM_STATUS_FINALIZED
  } nm_sr_event_t;
 
typedef struct nm_sr_request_s nm_sr_request_t;
 
typedef union
{
  struct
  {
    nm_gate_t p_gate;       
    nm_tag_t tag;           
    nm_len_t len;           
    nm_session_t p_session; 
    const struct nm_core_event_s*p_core_event; 
  } recv_unexpected; 
  struct
  {
    nm_sr_request_t*p_request; 
  } req; 
} nm_sr_event_info_t;
 
typedef void (*nm_sr_event_notifier_t)(nm_sr_event_t event, const nm_sr_event_info_t*event_info, void*ref);
 
struct nm_sr_monitor_s
{
  nm_sr_event_notifier_t p_notifier; 
  nm_sr_event_t event_mask; 
  nm_gate_t p_gate;         
  nm_tag_t tag;             
  nm_tag_t tag_mask;        
  void*ref;                 
};
 
/* ** Operations on requests (send or recv) **************** */
 
extern int nm_sr_request_monitor(nm_session_t p_session, nm_sr_request_t*p_request,
                                 nm_sr_event_t mask, nm_sr_event_notifier_t notifier);
 
static inline int nm_sr_request_monitor_with_ref(nm_session_t p_session, nm_sr_request_t*p_request,
                                                 nm_sr_event_t mask, nm_sr_event_notifier_t notifier, void*ref);
 
extern int nm_sr_request_set_completion_queue(nm_session_t p_session, nm_sr_request_t*p_request);
 
extern int nm_sr_request_unset_completion_queue(nm_session_t p_session, nm_sr_request_t*p_request);
 
static inline int nm_sr_request_isnull(nm_sr_request_t*p_request);
 
static inline int nm_sr_request_set_ref(nm_sr_request_t*p_request, void*ref);
 
static inline void*nm_sr_request_get_ref(nm_sr_request_t*p_request);
 
static inline nm_tag_t nm_sr_request_get_tag(nm_sr_request_t*p_request);
 
static inline int nm_sr_request_get_size(nm_sr_request_t*request, nm_len_t*size);
 
static inline int nm_sr_request_get_expected_size(nm_sr_request_t*request, nm_len_t*size);
 
static inline nm_gate_t nm_sr_request_get_gate(nm_sr_request_t*p_request);
 
static inline nm_session_t nm_sr_request_get_session(nm_sr_request_t*p_request);
 
extern int nm_sr_request_wait(nm_sr_request_t*p_request);
 
static inline void nm_sr_request_wait_all(nm_sr_request_t**p_requests, int n);
 
static inline int nm_sr_request_test(nm_sr_request_t*p_request);
 
static inline int nm_sr_request_test_status(nm_sr_request_t*p_request, nm_status_t status);
 
static inline int nm_sr_request_get_error(nm_sr_request_t*p_request);
 
extern int nm_sr_flush(struct nm_session_s*p_session);
 
 
/* ** Building blocks for send ***************************** */
 
/* Rationale for the send interface:
 *  either use the high-level interface (nm_sr_isend() et al., see below
 *  or the low-level building blocks
 * Sequence for a send with the low-level building blocks:
 *   1. nm_sr_send_init() init request
 *   2. nm_sr_send_pack_*() pack data into request
 *   3. nm_sr_send_isend|issend|rsend() to send data
 *      alternative:
 *        3.1 nm_sr_send_dest() set destination of message
 *        3.2 nm_sr_send_header() set data header size
 *        3.3 nm_sr_send_submit() submit send request to nmad
 */
 
static inline void nm_sr_send_init(nm_session_t p_session, nm_sr_request_t*p_request);
static inline void nm_sr_send_pack_contiguous(nm_session_t p_session, nm_sr_request_t*p_request,
                                              const void*, nm_len_t len);
static inline void nm_sr_send_pack_iov(nm_session_t p_session, nm_sr_request_t*p_request,
                                       const struct iovec*iov, int num_entries);
static inline void nm_sr_send_pack_data(nm_session_t p_session, nm_sr_request_t*p_request,
                                        const struct nm_data_s*p_data);
static inline int  nm_sr_send_isend(nm_session_t p_session, nm_sr_request_t*p_request,
                                    nm_gate_t p_gate, nm_tag_t tag);
static inline int  nm_sr_send_issend(nm_session_t p_session, nm_sr_request_t*p_request,
                                     nm_gate_t p_gate, nm_tag_t tag);
static inline int  nm_sr_send_rsend(nm_session_t p_session, nm_sr_request_t*p_request,
                                    nm_gate_t p_gate, nm_tag_t tag);
static inline int nm_sr_send_dest(nm_session_t p_session, nm_sr_request_t*p_request,
                                  nm_gate_t p_gate, nm_tag_t tag);
static inline int nm_sr_send_header(nm_session_t p_session, nm_sr_request_t*p_request, nm_len_t hlen);
static inline int nm_sr_send_submit(nm_session_t p_session, nm_sr_request_t*p_request);
static inline int nm_sr_send_submit_chunks(nm_session_t p_session, nm_sr_request_t*p_request,
                                           int n, const struct nm_chunk_s*p_chunks);
static inline void nm_sr_send_set_priority(nm_session_t p_session, nm_sr_request_t*p_request, nm_prio_t priority);
 
/* ** Building blocks for recv ***************************** */
 
static inline void nm_sr_recv_init(nm_session_t p_session, nm_sr_request_t*p_request);
static inline void nm_sr_recv_unpack_contiguous(nm_session_t p_session, nm_sr_request_t*p_request,
                                                void*ptr, nm_len_t len);
static inline void nm_sr_recv_unpack_iov(nm_session_t p_session, nm_sr_request_t*p_request,
                                         const struct iovec*iov, int num_entry);
static inline void nm_sr_recv_unpack_data(nm_session_t p_session, nm_sr_request_t*p_request,
                                          const struct nm_data_s*p_data);
static inline int nm_sr_recv_irecv(nm_session_t p_session, nm_sr_request_t*p_request,
                                   nm_gate_t p_gate, nm_tag_t tag, nm_tag_t mask);
static inline void nm_sr_recv_match(nm_session_t p_session, nm_sr_request_t*p_request,
                                    nm_gate_t p_gate, nm_tag_t tag, nm_tag_t mask);
static inline void nm_sr_recv_match_event(nm_session_t p_session, nm_sr_request_t*p_request,
                                          const nm_sr_event_info_t*p_event);
static inline int nm_sr_recv_peek(nm_session_t p_session, nm_sr_request_t*p_request,
                                   const struct nm_data_s*p_data);
 
static inline int nm_sr_recv_peek_offset(nm_session_t p_session, nm_sr_request_t*p_request,
                                         const struct nm_data_s*p_data, nm_len_t peek_offset, nm_len_t peek_len);
 
static inline void nm_sr_recv_offset(nm_session_t p_session, nm_sr_request_t*p_request, nm_len_t offset);
 
static inline int  nm_sr_recv_iprobe(nm_session_t p_session, nm_sr_request_t*p_request);
 
static inline void nm_sr_recv_data_wait(nm_session_t p_session, nm_sr_request_t*p_request);
 
static inline void nm_sr_recv_data_size_wait(nm_session_t p_session, nm_sr_request_t*p_request);
 
static inline int nm_sr_recv_data_test(nm_session_t p_session, nm_sr_request_t*p_request);
 
static inline int nm_sr_recv_post(nm_session_t p_session, nm_sr_request_t*p_request);
 
/* ** High level / legacy send ***************************** */
 
static inline int nm_sr_issend(nm_session_t p_session,
                               nm_gate_t p_gate, nm_tag_t tag,
                               const void*data, nm_len_t len,
                               nm_sr_request_t*p_request)
{
  nm_sr_send_init(p_session, p_request);
  nm_sr_send_pack_contiguous(p_session, p_request, data, len);
  const int err = nm_sr_send_issend(p_session, p_request, p_gate, tag);
  return err;
}
 
static inline int nm_sr_isend(nm_session_t p_session,
                              nm_gate_t p_gate, nm_tag_t tag,
                              const void*data, nm_len_t len,
                              nm_sr_request_t*p_request)
{
  nm_sr_send_init(p_session, p_request);
  nm_sr_send_pack_contiguous(p_session, p_request, data, len);
  const int err = nm_sr_send_isend(p_session, p_request, p_gate, tag);
  return err;
}
 
static inline int nm_sr_rsend(nm_session_t p_session,
                              nm_gate_t p_gate, nm_tag_t tag,
                              const void*data, nm_len_t len,
                              nm_sr_request_t*p_request)
{
  nm_sr_send_init(p_session, p_request);
  nm_sr_send_pack_contiguous(p_session, p_request, data, len);
  const int err = nm_sr_send_rsend(p_session, p_request, p_gate, tag);
  return err;
}
 
static inline int nm_sr_isend_iov(nm_session_t p_session,
                                  nm_gate_t p_gate, nm_tag_t tag,
                                  const struct iovec *iov, int num_entries,
                                  nm_sr_request_t*p_request)
{
  nm_sr_send_init(p_session, p_request);
  nm_sr_send_pack_iov(p_session, p_request, iov, num_entries);
  const int err = nm_sr_send_isend(p_session, p_request, p_gate, tag);
  return err;
}
 
static inline int nm_sr_isend_data(nm_session_t p_session,
                                   nm_gate_t p_gate, nm_tag_t tag,
                                   struct nm_data_s*p_data,
                                   nm_sr_request_t*p_request)
{
  nm_sr_send_init(p_session, p_request);
  nm_sr_send_pack_data(p_session, p_request, p_data);
  const int err = nm_sr_send_isend(p_session, p_request, p_gate, tag);
  return err;
}
 
 
extern int nm_sr_stest(nm_session_t p_session,
                       nm_sr_request_t*p_request);
 
extern int nm_sr_progress(nm_session_t p_session);
 
static inline int nm_sr_swait(nm_session_t p_session, nm_sr_request_t*p_request);
 
extern int nm_sr_scancel(nm_session_t p_session,
                         nm_sr_request_t*p_request);
 
 
static inline int nm_sr_irecv(nm_session_t p_session,
                              nm_gate_t p_gate, nm_tag_t tag,
                              void*data, nm_len_t len,
                              nm_sr_request_t*p_request)
{
  nm_sr_recv_init(p_session, p_request);
  nm_sr_recv_unpack_contiguous(p_session, p_request, data, len);
  nm_sr_recv_irecv(p_session, p_request, p_gate, tag, NM_TAG_MASK_FULL);
  return NM_ESUCCESS;
}
 
static inline int nm_sr_irecv_iov(nm_session_t p_session,
                                  nm_gate_t p_gate, nm_tag_t tag,
                                  struct iovec *iov, int num_entries,
                                  nm_sr_request_t*p_request)
{
  nm_sr_recv_init(p_session, p_request);
  nm_sr_recv_unpack_iov(p_session, p_request, iov, num_entries);
  return nm_sr_recv_irecv(p_session, p_request, p_gate, tag, NM_TAG_MASK_FULL);
}
 
static inline int nm_sr_irecv_data(nm_session_t p_session,
                                   nm_gate_t p_gate, nm_tag_t tag,
                                   struct nm_data_s*p_data,
                                   nm_sr_request_t*p_request)
{
  nm_sr_recv_init(p_session, p_request);
  nm_sr_recv_unpack_data(p_session, p_request, p_data);
  return nm_sr_recv_irecv(p_session, p_request, p_gate, tag, NM_TAG_MASK_FULL);
}
 
static inline int nm_sr_request_monitor_with_ref(nm_session_t p_session, nm_sr_request_t*p_request,
                                                 nm_sr_event_t mask, nm_sr_event_notifier_t notifier, void*ref)
{
  nm_sr_request_set_ref(p_request, ref);
  return nm_sr_request_monitor(p_session, p_request, mask, notifier);
}
 
 
extern int nm_sr_rtest(nm_session_t p_session, nm_sr_request_t*p_request);
 
 
static inline int nm_sr_rwait(nm_session_t p_session, nm_sr_request_t*p_request);
 
static inline int nm_sr_rwait_data(nm_session_t p_session, nm_sr_request_t*p_request);
 
extern int nm_sr_rcancel(nm_session_t p_session, nm_sr_request_t*p_request);
 
extern int nm_sr_recv_source(nm_session_t p_session,
                             nm_sr_request_t*p_request, nm_gate_t*p_gate);
 
extern int nm_sr_probe(nm_session_t p_session,
                       nm_gate_t p_gate, nm_gate_t*p_out_gate,
                       nm_tag_t tag, nm_tag_t tag_mask, nm_tag_t*p_out_tag,
                       nm_len_t*p_out_len);
 
int nm_sr_session_monitor_set(nm_session_t p_session, const struct nm_sr_monitor_s*p_monitor);
 
int nm_sr_session_monitor_remove(nm_session_t p_session, const struct nm_sr_monitor_s*p_monitor);
 
extern int nm_sr_recv_success(nm_session_t p_session, nm_sr_request_t**out_req);
 
extern int nm_sr_send_success(nm_session_t p_session, nm_sr_request_t**out_req);
 
 
 
#include <nm_sendrecv_private.h> /* private header included for inlining */
 
static inline int nm_sr_send(nm_session_t p_session,
                             nm_gate_t p_gate, nm_tag_t tag,
                             const void*data, nm_len_t len)
{
  nm_sr_request_t request;
  int rc = nm_sr_isend(p_session, p_gate, tag, data, len, &request);
  if(rc == NM_ESUCCESS)
    {
      rc = nm_sr_swait(p_session, &request);
    }
  return rc;
}
 
static inline int nm_sr_recv(nm_session_t p_session,
                             nm_gate_t p_gate, nm_tag_t tag,
                             void*data, nm_len_t len)
{
  nm_sr_request_t request;
  int rc = nm_sr_irecv(p_session, p_gate, tag, data, len, &request);
  if(rc == NM_ESUCCESS)
    {
      rc = nm_sr_rwait(p_session, &request);
    }
  return rc;
}
 
static inline int nm_sr_send_data(nm_session_t p_session, nm_gate_t p_gate, nm_tag_t tag, struct nm_data_s*p_data)
{
  nm_sr_request_t request;
  int rc = nm_sr_isend_data(p_session, p_gate, tag, p_data, &request);
  if(rc == NM_ESUCCESS)
    {
      rc = nm_sr_swait(p_session, &request);
    }
  return rc;
}
 
static inline int nm_sr_recv_data(nm_session_t p_session, nm_gate_t p_gate, nm_tag_t tag, struct nm_data_s*p_data)
{
  nm_sr_request_t request;
  int rc = nm_sr_irecv_data(p_session, p_gate, tag, p_data, &request);
  if(rc == NM_ESUCCESS)
    {
      rc = nm_sr_rwait(p_session, &request);
    }
  return rc;
}
 
NM_EXTERN_C_END
 
#endif /* NM_SENDRECV_INTERFACE_H */