m0_rpc_session Struct Reference

#include <session.h>

Collaboration diagram for m0_rpc_session:

Data Fields
uint64_t	s_session_id
struct m0_rpc_conn *	s_conn
struct m0_tlink	s_link
uint32_t	s_hold_cnt
struct m0_sm	s_sm
uint64_t	s_magic
uint64_t	s_xid
struct m0_tl	s_xid_list
struct m0_rpc_item_cache	s_reply_cache
struct m0_rpc_item_cache	s_req_cache
bool	s_cancelled
struct m0_tl	s_pending_cache

Detailed Description

Rpc connection can be shared by multiple entities (e.g. users) by creating their own "session" on the connection. A session can be used to maintain authentication information or QoS parameters.

Liveness:

On sender side, allocation and deallocation of m0_rpc_session is entirely managed by user except for SESSION 0. SESSION 0 is allocated and deallocated by rpc-layer internally along with m0_rpc_conn.

See also

m0_rpc_conn for more information on creation and use of SESSION 0.

On receiver side, m0_rpc_session object will be allocated and deallocated by rpc-layer internally, in response to session create and session terminate requests respectively.

Concurrency:

Users of rpc-layer are never expected to take lock on session. Rpc layer will internally synchronise access to m0_rpc_session.

All access to session are synchronized using session->s_conn->c_rpc_machine->rm_sm_grp.s_lock.

When session is in one of INITIALISED, TERMINATED, FINALISED and FAILED state, user is expected to serialise access to the session object. (It is assumed that session, in one of {INITIALISED, TERMINATED, FAILED, FINALISED} states, does not have concurrent users).

                                    |
                                    |m0_rpc_session_init()
m0_rpc_session_establish() != 0     V
        +----------------------INITIALISED
        |                           |
        |                           | m0_rpc_session_establish()
        |                           |
        |     timed-out             V
        +-----------------------ESTABLISHING
        |   create_failed           | create successful/n = 0
        V                           |
      FAILED <------+               |   n == 0
        |           |               +-----------------+
        |           |               |                 | +-----+
        |           |failed         |                 | |     | item add/n++
        |           |               V  item add/n++   | V     | reply rcvd/n--
        |           +-------------IDLE--------------->BUSY----+
        |           |               |
        | fini()    |               | m0_rpc_session_terminate()
        |           |               V
        |           +----------TERMINATING
        |                           |
        |                           |
        |                           |
        |                           |session_terminated
        |                           V
        |                       TERMINATED
        |                           |
        |                           | fini()
        |                           V
        +----------------------> FINALISED

Typical sequence of execution of APIs on sender side. Error checking is omitted.

// ALLOCATE SESSION

struct m0_rpc_session *session;
M0_ALLOC_PTR(session);

// INITIALISE SESSION

rc = m0_rpc_session_init(session, conn);
M0_ASSERT(ergo(rc == 0, session_state(session) ==
                        M0_RPC_SESSION_INITIALISED));

// ESTABLISH SESSION

rc = m0_rpc_session_establish(session);

rc = m0_rpc_session_timedwait(session, M0_BITS(M0_RPC_SESSION_IDLE,
                                         M0_RPC_SESSION_FAILED),
                        timeout);

if (rc == 0 && session_state(session) == M0_RPC_SESSION_IDLE) {
     // Session is successfully established
} else {
     // timeout has happened or session establish failed
}

// Assuming session is successfully established.
// post unbound items using m0_rpc_post(item)

item->ri_session = session;
item->ri_prio = M0_RPC_ITEM_PRIO_MAX;
item->ri_deadline = absolute_time;
item->ri_ops = item_ops;   // item_ops contains ->replied() callback which
                     // will be called when reply to this item is
                     // received. DO NOT FREE THIS ITEM.

rc = m0_rpc_post(item);

// TERMINATING SESSION
// Wait until all the items that were posted on this session, are sent and
// for all those items either reply is received or reply_timeout has
// triggered.
m0_rpc_session_timedwait(session, M0_BITS(M0_RPC_SESSION_IDLE), timeout);
M0_ASSERT(session_state == M0_RPC_SESSION_IDLE);
rc = m0_rpc_session_terminate(session);
if (rc == 0) {
     // Wait until session is terminated.
     rc = m0_rpc_session_timedwait(session,
                             M0_BITS(M0_RPC_SESSION_TERMINATED,
                                     M0_RPC_SESSION_FAILED),
                             timeout);
}

// FINALISE SESSION

m0_rpc_session_fini(session);
m0_free(session);

Receiver is not expected to call any of these APIs. Receiver side session structures will be set-up while handling fops m0_rpc_fop_[conn|session]_[establish|terminate].

When receiver needs to post reply, it uses m0_rpc_reply_post().

m0_rpc_reply_post(request_item, reply_item);

m0_rpc_reply_post() will copy all the session related information from request item to reply item and process reply item.

Note: rpc connection is a two-way communication channel. There are requests and corresponding reply items, on the same connection. Receiver NEED NOT have to establish other separate connection with sender, to be able to send replies.

Definition at line 305 of file session.h.

Field Documentation

s_cancelled

bool s_cancelled

Flag to indicate if this session has been cancelled. This flag is set to TRUE at the beginning of m0_rpc_session_cancel() execution. Once this flag is set to TRUE, subsequent m0_rpc_post() against the same session returns -ECANCELED error.

Definition at line 360 of file session.h.

s_conn

struct m0_rpc_conn* s_conn

rpc connection on which this session is created

Definition at line 312 of file session.h.

s_hold_cnt

uint32_t s_hold_cnt

if > 0, then session is in BUSY state

Definition at line 320 of file session.h.

s_link

struct m0_tlink s_link

Link in RPC conn. m0_rpc_conn::c_sessions List descriptor: session

Definition at line 317 of file session.h.

s_magic

uint64_t s_magic

M0_RPC_SESSION_MAGIC

Definition at line 328 of file session.h.

s_pending_cache

struct m0_tl s_pending_cache

Items submitted to formation. Required in case RPC session is to be cancelled so as to cancel all such items. This cache is protected with rpc machine lock.

Definition at line 368 of file session.h.

s_reply_cache

struct m0_rpc_item_cache s_reply_cache

Replies to resend if needed. This cache is protected with rpc machine lock.

Definition at line 345 of file session.h.

s_req_cache

struct m0_rpc_item_cache s_req_cache

Requests which are handled already. This cache is protected with rpc machine lock.

Definition at line 351 of file session.h.

s_session_id

uint64_t s_session_id

identifies a particular session. Unique in all sessions belonging to same m0_rpc_conn

Definition at line 309 of file session.h.

s_sm

struct m0_sm s_sm

RPC session state machine

See also

m0_rpc_session_state, session_conf

Definition at line 325 of file session.h.

s_xid

uint64_t s_xid

Unique item identifier counter

Definition at line 331 of file session.h.

s_xid_list

struct m0_tl s_xid_list

List of all rpc items in the session that have xid and are going to be sent. Items in the list are in osr_xid increasing order.

See also

m0_rpc_item:ri_xid_link, m0_rpc_item_xid_min_update(), xidl.

Definition at line 339 of file session.h.

---

The documentation for this struct was generated from the following file:

• rpc/session.h