Difference between revisions of "Libsoccr"

From CRIU
Jump to: navigation, search
(Data types)
Line 23: Line 23:
 
== Data types ==
 
== Data types ==
  
In soccr/soccr.h there are two types declares
+
In soccr/soccr.h there are three types declares
  
 
; <code>struct libsoccr_sk</code>
 
; <code>struct libsoccr_sk</code>
Line 30: Line 30:
 
; <code>struct libsoccr_sk_data</code>
 
; <code>struct libsoccr_sk_data</code>
 
: A structure containing a set of 32-bit values that are returned by ''getter'' and that are to be passed '''as is''' to the ''setter'' call
 
: A structure containing a set of 32-bit values that are returned by ''getter'' and that are to be passed '''as is''' to the ''setter'' call
 +
 +
; <code>struct libsoccr_addr</code>
 +
: A structure that defines soccaddr for a socket. It's used by set/get calls described further.
  
 
=== Data internals ===
 
=== Data internals ===
  
Inside the data structure there's a special field called <code>flags</code> that gives information about the meaning of some other fields. Though it's not bad just to pass this structure as-is between libsoccr calls, doing some optimization based on flags is OK.
+
Inside the <code>libsoccr_sk_data</code> structure there's a special field called <code>flags</code> that gives information about the meaning of some other fields. Though it's not bad just to pass this structure as-is between libsoccr calls, doing some optimization based on flags is OK.
  
 
So here are the flags that make sense
 
So here are the flags that make sense

Revision as of 11:18, 11 January 2017

Libsoccr is the library that does TCP connection checkpoint and restore. It sits in criu sources and includes an API header and a static library.

Overview

To checkpoint a TCP connection one should

  1. pause a socket (referenced by descriptor)
  2. get socket data
  3. get contents of two queues
  4. (optionally) resume the socket
  5. close it

To restore a connection one should

  1. create a socket
  2. pause one
  3. restore unbound data
  4. bind() and/or connect() socket to whatever addresses is appropriate using standard calls
  5. restore noq data
  6. put contents of two queues
  7. restore remaining data

Data types

In soccr/soccr.h there are three types declares

struct libsoccr_sk
It's an abstract handler returned by pausing routine that is used as an opaque identifier by the rest of the libsoccr calls
struct libsoccr_sk_data
A structure containing a set of 32-bit values that are returned by getter and that are to be passed as is to the setter call
struct libsoccr_addr
A structure that defines soccaddr for a socket. It's used by set/get calls described further.

Data internals

Inside the libsoccr_sk_data structure there's a special field called flags that gives information about the meaning of some other fields. Though it's not bad just to pass this structure as-is between libsoccr calls, doing some optimization based on flags is OK.

So here are the flags that make sense

SOCCR_FLAGS_WINDOW == 0x1
When set indicates, that fields snd_wl1, snd_wnd, max_window, rcv_wnd and rcv_wup contain some valuable data (0 is valid value for any)

Calls

Generic

struct libsoccr_sk *libsoccr_pause(int sk)
Pauses the socket and returns a handler for further operations. Any data flow for this socket must be blocked by the caller before this call.
void libsoccr_resume(struct libsoccr_sk *)
Resumes the socket. Data flow unlock may happen before this.
void libsoccr_set_log(unsigned int level, void (*fn)(unsigned int level, const char *fmt, ...))
Sets a function that will be called when libsoccr will want to print something on the screen.

Dump

int libsoccr_get_sk_data(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)
Fills in the data structure with the info get from paused socket. The data_size should be the size of the structure passed. The return code is the size of the structure really filled with data.
char *libsoccr_get_queue_bytes(struct libsoccr_sk *sk, int queue_id, int steal)
Returns a malloc()-ed array with the contents of the queue. The queue can be TCP_RECV_QUEUE or TCP_SEND_QUEUE. The amount of bytes in each is data.inq_len and data.outq_len respectively. The steal is a boolean value specifying whether the caller would free() the buffers himself (1) or expects the _resume() to do it (0).

Restore

int libsoccr_set_sk_data_unbound(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)
Restores data on a socket from the data structure. Should be called before bind()-ing or connect()-ing the socket.
int libsoccr_set_sk_data_noq(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)
Continues restoration after bind() and/or connect(), but before the queue data restore (see below)
int libsoccr_set_sk_data(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)
Completes the restoration after queues, but doesn't resume the socket.
int libsoccr_set_queue_bytes(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size, int queue, char *buf)
Puts back the contents of the respective queue.