Libsoccr - Revision history

Kir: /* Example */ use source tag

2017-01-26T02:28:09Z

Example: use source tag

Kir: reword the intro, use template:criu

2017-01-25T05:59:41Z

reword the intro, use template:criu

Avagin: /* Flags */

2017-01-19T19:58:34Z

Flags

Xemul at 09:09, 16 January 2017

2017-01-16T09:09:50Z

Xemul: /* Generic */

2017-01-16T08:04:31Z

Generic

Kir: use source highlighting

2017-01-13T21:07:03Z

use source highlighting

Kir: minor rewording here and there

2017-01-13T20:59:24Z

minor rewording here and there

Xemul: /* Dump */

2017-01-11T11:26:09Z

Dump

Xemul at 11:25, 11 January 2017

2017-01-11T11:25:33Z

Xemul: /* Calls */

2017-01-11T11:23:42Z

Calls

@@ Line 94: / Line 94: @@
 [[Category: Sockets]]
 == Example ==
-<tt> <pre>
 /* Dump a tcp socket */
@@ Line 139: / Line 140: @@
 libsoccr_resume(so_rst);
 libsoccr_resume(so);
-</pre>
+</source>

← Older revision		Revision as of 05:59, 25 January 2017
Line 1:		Line 1:
−	Libsoccr is ~~the~~ library that does [[TCP connection]] checkpoint and restore. ~~Currently it~~ resides in criu source code (<code>soccr</code> subdirectory) and consists of an API header and a static library. ~~Available~~ since ~~[[Download/~~criu/2.10~~\|Waxwing~~ release]].	+	Libsoccr is a library that does [[TCP connection]] checkpoint and restore.
		+
		+	Libsoccr resides in criu source code (<code>soccr</code> subdirectory) and consists of an API header and a static library.
		+
		+	Libsoccr is available since CRIU {{criu\|2.10}} release.

	== Overview ==		== Overview ==

← Older revision		Revision as of 19:58, 19 January 2017
Line 89:		Line 89:
	[[Category: Sub-projects]]		[[Category: Sub-projects]]
	[[Category: Sockets]]		[[Category: Sockets]]
		+	== Example ==
		+	<tt> <pre>
		+	/* Dump a tcp socket */
		+
		+	dst_let = sizeof(addr);
		+	if (getsockname(sock, (struct sockaddr *) &addr, &dst_let)) {
		+	pr_perror("connect");
		+	return -1;
		+	}
		+	dst_let = sizeof(addr);
		+	if (getpeername(sock, (struct sockaddr *) &dst, &dst_let)) {
		+	pr_perror("connect");
		+	return -1;
		+	}
		+
		+	so = libsoccr_pause(sock);
		+
		+	dsize = libsoccr_save(so, &data, sizeof(data));
		+	if (dsize < 0) {
		+	pr_perror("libsoccr_save");
		+	return -1;
		+	}
		+	close(sock);
		+
		+
		+	/* Restore a tcp socket */
		+	rst = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
		+	if (rst == -1)
		+	return -1;
		+
		+
		+	so_rst = libsoccr_pause(rst);
		+	libsoccr_set_addr(so_rst, 1, &addr, 0);
		+	libsoccr_set_addr(so_rst, 0, &dst, 0);
		+
		+	queue = libsoccr_get_queue_bytes(so, TCP_RECV_QUEUE, SOCCR_MEM_EXCL);
		+	libsoccr_set_queue_bytes(so_rst, TCP_RECV_QUEUE, queue, SOCCR_MEM_EXCL);
		+	queue = libsoccr_get_queue_bytes(so, TCP_SEND_QUEUE, SOCCR_MEM_EXCL);
		+	libsoccr_set_queue_bytes(so_rst, TCP_SEND_QUEUE, queue, SOCCR_MEM_EXCL);
		+
		+	ret = libsoccr_restore(so_rst, &data, dsize);
		+	if (ret)
		+	return -1;
		+
		+	libsoccr_resume(so_rst);
		+	libsoccr_resume(so);
		+	</pre>
		+	</tt>

← Older revision		Revision as of 09:09, 16 January 2017
Line 1:		Line 1:
−	Libsoccr is the library that does [[TCP connection]] checkpoint and restore. Currently it resides in criu source code (<code>soccr</code> subdirectory) and consists of an API header and a static library.	+	Libsoccr is the library that does [[TCP connection]] checkpoint and restore. Currently it resides in criu source code (<code>soccr</code> subdirectory) and consists of an API header and a static library. Available since [[Download/criu/2.10\|Waxwing release]].

	== Overview ==		== Overview ==

@@ Line 51: / Line 51: @@
 ; <source lang="c" inline>void libsoccr_resume(struct libsoccr_sk *)</source>
-: Resumes the socket. Data flow unlock may happen before this.
+: Resumes the socket and frees the handler. Data flow unlock may happen before this.
 ; <source lang="c" inline>void libsoccr_set_log(unsigned int level, void (*fn)(unsigned int level, const char *fmt, ...))</source>

@@ Line 25: / Line 25: @@
 soccr/soccr.h declares three types:
-; <code>struct libsoccr_sk</code>
+; <source lang="c" inline>struct libsoccr_sk</source>
 : An abstract handler returned by ''pausing'' routine that is used as an opaque identifier by the rest of the libsoccr calls
-; <code>struct libsoccr_sk_data</code>
+; <source lang="c" inline>struct libsoccr_sk_data</source>
 : 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>
+; <source lang="c" inline>struct libsoccr_addr</source>
 : A structure that defines soccaddr for a socket. It's used by set/get calls described further.
@@ Line 40: / Line 40: @@
 Here are the flags that make sense:
-; <code>SOCCR_FLAGS_WINDOW == 0x1</code>
+; <source lang="c" inline>SOCCR_FLAGS_WINDOW == 0x1</source>
 : When set, indicates that fields <code>snd_wl1</code>, <code>snd_wnd</code>, <code>max_window</code>, <code>rcv_wnd</code> and <code>rcv_wup</code> contain some valuable data (0 is a valid value for any of these)
@@ Line 47: / Line 47: @@
 === Generic ===
-; <code>struct libsoccr_sk *libsoccr_pause(int sk)</code>
+; <source lang="c" inline>struct libsoccr_sk *libsoccr_pause(int sk)</source>
 : 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.
-; <code>void libsoccr_resume(struct libsoccr_sk *)</code>
+; <source lang="c" inline>void libsoccr_resume(struct libsoccr_sk *)</source>
 : Resumes the socket. Data flow unlock may happen before this.
-; <code>void libsoccr_set_log(unsigned int level, void (*fn)(unsigned int level, const char *fmt, ...))</code>
+; <source lang="c" inline>void libsoccr_set_log(unsigned int level, void (*fn)(unsigned int level, const char *fmt, ...))</source>
 : Sets a function that will be called when libsoccr will want to print something on the screen.
 === Dump ===
-; <code>int libsoccr_save(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</code>
+; <source lang="c" inline>int libsoccr_save(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</source>
 : Fills in the <code>data</code> structure with the info get from paused socket. The <code>data_size</code> should be the size of the structure passed. The return code is the size of the structure really filled with data.
-; <code>char *libsoccr_get_queue_bytes(struct libsoccr_sk *sk, int queue_id, unsigned flags)</code>
+; <source lang="c" inline>char *libsoccr_get_queue_bytes(struct libsoccr_sk *sk, int queue_id, unsigned flags)</source>
 : 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 <code>data.inq_len</code> and <code>data.outq_len</code> respectively. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below).
-; <code>union libsoccr_addr *libsoccr_get_addr(struct libsoccr_sk *sk, int self, unsigned flags)</code>  (currently unimplemented and returns NULL)
+; <source lang="c" inline>union libsoccr_addr *libsoccr_get_addr(struct libsoccr_sk *sk, int self, unsigned flags)</source>  (currently unimplemented and returns NULL)
 : Returns address (self or peer) of the socket. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below)
 === Restore ===
-; <code>int libsoccr_restore(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</code>
+; <source lang="c" inline>int libsoccr_restore(struct libsoccr_sk *sk, struct libsoccr_sk_data *data, unsigned data_size)</source>
 : Restores data on a socket from the <code>data</code> structure. Should be called after the calls below, but before the "resume" one.
-; <code>int libsoccr_set_queue_bytes(struct libsoccr_sk *sk, int queue, char *buf, unsigned flags)</code>
+; <source lang="c" inline>int libsoccr_set_queue_bytes(struct libsoccr_sk *sk, int queue, char *buf, unsigned flags)</source>
 : Puts back the contents of the respective queue. The <code>flags</code> may contain <code>SOCCR_MEM_EXCL</code>.
-; <code>int libsoccr_set_addr(struct libsoccr_sk *sk, int self, union libsoccr_addr *, unsigned flags)</code>
+; <source lang="c" inline>int libsoccr_set_addr(struct libsoccr_sk *sk, int self, union libsoccr_addr *, unsigned flags)</source>
 : Sets address (self or peer) of the socket. The <code>flags</code> may contain <code>SOCCR_MEM_EXCL</code>.

@@ Line 1: / Line 1: @@
-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.
+Libsoccr is the library that does [[TCP connection]] checkpoint and restore. Currently it resides in criu source code (<code>soccr</code> subdirectory) and consists of an API header and a static library.
 == Overview ==
-To checkpoint a TCP connection one should
+To checkpoint a TCP connection, one should
 # ''pause'' a socket (referenced by descriptor)
@@ Line 11: / Line 11: @@
 # close it
-To restore a connection one should
+To restore a connection, one should
 # create a socket
@@ Line 23: / Line 23: @@
 == Data types ==
-In soccr/soccr.h there are three types declares
+soccr/soccr.h declares three types:
 ; <code>struct libsoccr_sk</code>
-: It's an abstract handler returned by ''pausing'' routine that is used as an opaque identifier by the rest of the libsoccr calls
+: An abstract handler returned by ''pausing'' routine that is used as an opaque identifier by the rest of the libsoccr calls
 ; <code>struct libsoccr_sk_data</code>
@@ Line 38: / Line 38: @@
 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
+Here are the flags that make sense:
 ; <code>SOCCR_FLAGS_WINDOW == 0x1</code>
-: When set indicates, that fields <code>snd_wl1</code>, <code>snd_wnd</code>, <code>max_window</code>, <code>rcv_wnd</code> and <code>rcv_wup</code> contain some valuable data (0 is valid value for any)
+: When set, indicates that fields <code>snd_wl1</code>, <code>snd_wnd</code>, <code>max_window</code>, <code>rcv_wnd</code> and <code>rcv_wup</code> contain some valuable data (0 is a valid value for any of these)
 == Calls ==
@@ Line 62: / Line 62: @@
 ; <code>char *libsoccr_get_queue_bytes(struct libsoccr_sk *sk, int queue_id, unsigned flags)</code>
-: 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 <code>data.inq_len</code> and <code>data.outq_len</code> respectively. The <code>flags</code> may include <code>SOCCR_MEM_EXCL</code> bit (see below).
+: 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 <code>data.inq_len</code> and <code>data.outq_len</code> respectively. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below).
 ; <code>union libsoccr_addr *libsoccr_get_addr(struct libsoccr_sk *sk, int self, unsigned flags)</code>  (currently unimplemented and returns NULL)
-: Returns address (self or peer) of the socket. The <code>flags</code> may include <code>SOCCR_MEM_EXCL</code> bit (see below)
+: Returns address (self or peer) of the socket. The <code>flags</code> may have <code>SOCCR_MEM_EXCL</code> bit set (see below)
 === Restore ===
@@ Line 79: / Line 79: @@
 == Flags ==
-Here are the flags, that are accepted by various calls.
+Here are the flags accepted by various calls.
 ; <code>SOCCR_MEM_EXCL</code>
-: This flag means that the memory buffer set or get by the call is managed and should be freed by the recipient, i.e. when set the libsoccr will free() it, when get libsoccr won't do it expecting the caller to.
+: Tells that the memory buffer set or get by the call is to be managed (and should be freed) by the ''receiving side''. In case of a get call the receiving side is the caller program, meaning it has to free() the buffer. In case of a set call the receiver is libsoccr, meaning libsoccr has to free() it.
 [[Category: Sub-projects]]
 [[Category: Sockets]]