Changeset 745 for trunk/server/lib/tsocket/tsocket_guide.txt

Timestamp:

Nov 27, 2012, 4:43:17 PM (13 years ago)

Author:

Silvan Scherrer

Message:

Samba Server: updated trunk to 3.6.0

Location:

trunk/server

Files:

• . (modified) (1 prop)
• lib/tsocket/tsocket_guide.txt (modified) (15 diffs)

trunk/server/lib/tsocket/tsocket_guide.txt

@@ -24 +24 @@
 ===============================
 
-The tsocket_address represents an socket endpoint genericly.
-As it's like an abstract class it has no specific constructor.
-The specific constructors are descripted later sections.
-
-There's a function get the string representation of the
-endpoint for debugging. Callers should not try to parse
-the string! The should use additional methods of the specific
-tsocket_address implemention to get more details.
+A tsocket_address represents a generic socket endpoint.
+It behaves like an abstract class, therefore it has no direct constructor.
+Constructors are described in later sections of this document.
+
+A function get the string representation of an endpoint for debugging is
+available but callers SHOULD NOT try to parse this string. To get more
+details callers should use getter methods of the specific tsocket_address
+implemention.
 
   char *tsocket_address_string(const struct tsocket_address *addr,
       TALLOC_CTX *mem_ctx);
 
-There's a function to create a copy of the tsocket_address.
-This is useful when before doing modifications to a socket
+A function to create a copy of the tsocket_address is also avilable.
+This is useful before doing modifications to a socket
 via additional methods of the specific tsocket_address implementation.
 
@@ -48 +48 @@
 The tdgram_context is like an abstract class for datagram
 based sockets. The interface provides async 'tevent_req' based
-functions on top functionality is similar to the
-recvfrom(2)/sendto(2)/close(2) syscalls.
+functions similar to recvfrom(2)/sendto(2)/close(2) syscalls.
 
 The tdgram_recvfrom_send() method can be called to ask for the
-next available datagram on the abstracted tdgram_context.
+next available datagram from the abstracted tdgram_context.
 It returns a 'tevent_req' handle, where the caller can register
 a callback with tevent_req_set_callback(). The callback is triggered
-when a datagram is available or an error happened.
+when a datagram is available or an error occurs.
 
 The callback is then supposed to get the result by calling
@@ -123 +122 @@
 ===============================
 
-The tstream_context is like an abstract class for stream
+A tstream_context is like an abstract class for stream
 based sockets. The interface provides async 'tevent_req' based
-functions on top functionality is similar to the
-readv(2)/writev(2)/close(2) syscalls.
-
-The tstream_pending_bytes() function is able to report
-how much bytes of the incoming stream have arrived
-but not consumed yet. It returns -1 and sets 'errno' on failure.
-Otherwise it returns the number of uncomsumed bytes
-(it can return 0!).
+functions similar to the readv(2)/writev(2)/close(2) syscalls.
+
+The tstream_pending_bytes() function is able to report how many bytes of
+the incoming stream have been received but have not been consumed yet.
+It returns -1 and sets 'errno' on failure.
+Otherwise it returns the number of uncomsumed bytes (it can return 0!).
 
   ssize_t tstream_pending_bytes(struct tstream_context *stream);
 
-The tstream_readv_send() method can be called to read for a
+The tstream_readv_send() method can be called to read a
 specific amount of bytes from the stream into the buffers
 of the given iovec vector. The caller has to preallocate the buffers
@@ -144 +141 @@
 where the caller can register a callback with tevent_req_set_callback().
 The callback is triggered when all iovec buffers are completely
-filled with bytes from the socket or an error happened.
+filled with bytes from the socket or an error occurs.
 
 The callback is then supposed to get the result by calling
 tstream_readv_recv() on the 'tevent_req'. It returns -1
 and sets '*perrno' to the actual 'errno' on failure.
-Otherwise it returns the length of the datagram
-(0 is never returned!).
+Otherwise it returns the length of the datagram (0 is never returned!).
 
 The caller can only have one outstanding tstream_readv_send()
@@ -166 +162 @@
 The tstream_writev_send() method can be called to write
 buffers in the given iovec vector into the stream socket.
-It's invalid to pass an empty vector.
+It is invalid to pass an empty vector.
 tstream_writev_send() returns a 'tevent_req' handle,
 where the caller can register a callback with tevent_req_set_callback().
@@ -190 +186 @@
       int *perrno);
 
-The tstream_disconnect_send() method should be used to normally
+The tstream_disconnect_send() method should normally be used to
 shutdown/close the abstracted socket.
 
@@ -209 +205 @@
 ============================
 
-In order to make the live easier for callers which want to implement
+In order to simplify the job, for callers that want to implement
 a function to receive a full PDU with a single async function pair,
-there're some helper functions.
+some helper functions are provided.
 
 The caller can use the tstream_readv_pdu_send() function
@@ -217 +213 @@
 The caller needs to provide a "next_vector" function and a private
 state for this function. The tstream_readv_pdu engine will ask
-the next_vector function for the next iovec vetor to be filled.
+the next_vector function for the next iovec vector to be used.
 There's a tstream_readv_send/recv pair for each vector returned
 by the next_vector function. If the next_vector function detects
@@ -223 +219 @@
 of the tevent_req (returned by tstream_readv_pdu_send()) is triggered.
 Note: the buffer allocation is completely up to the next_vector function
-and it's private state.
+and its private state.
 
 See the 'dcerpc_read_ncacn_packet_send/recv' functions in Samba as an
@@ -245 +241 @@
 ===========================================
 
-There're some cases where the caller wants doesn't care about the
-order of doing IO on the abstracted sockets.
+In some cases the caller doesn't care about the IO ordering on the
+abstracted socket.
 (Remember at the low level there's always only one IO in a specific
  direction allowed, only one tdgram_sendto_send() at a time).
 
-There're some helpers using 'tevent_queue' to make it easier
-for callers. The functions just get a 'queue' argument
-and serialize the operations.
+Some helpers that use 'tevent_queue' are avilable to simplify handling
+multiple IO requests. The functions just get a 'queue' argument and
+internally serialize all operations.
 
   struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx,
@@ -296 +292 @@
 (dns names are not allowed!). But it's valid to pass NULL,
 which gets mapped to "0.0.0.0" or "::".
-It return -1 and set errno on error. Otherwise it returns 0.
+It returns -1 and sets errno on error. Otherwise it returns 0.
 
   int tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
@@ -343 +339 @@
 you can use the tsocket_address_unix_path() function.
 It will return NULL and set errno to EINVAL if the tsocket_address
-doesn't represent an unix domain endpoint path.
+doesn't represent a unix domain endpoint path.
 
   char *tsocket_address_unix_path(const struct tsocket_address *addr,
@@ -372 +368 @@
       struct tdgram_context **dgram);
 
-You can use tstream_inet_tcp_connect_send to async
+You can use tstream_inet_tcp_connect_send to asynchronously
 connect to a remote ipv4 or ipv6 TCP endpoint and create a
 tstream_context for the stream based communication. "local_address" has to be
@@ -398 +394 @@
       struct tstream_context **stream);
 
-You can use tstream_unix_connect_send to async
+You can use tstream_unix_connect_send to asynchronously
 connect to a unix domain endpoint and create a
 tstream_context for the stream based communication.
@@ -439 +435 @@
 for that. This should only be used if really needed, because of
 already existing fixed APIs. Only AF_INET, AF_INET6 and AF_UNIX
-sockets are allowed. The function returns -1 and set errno on error.
+sockets are allowed. The function returns -1 and sets errno on error.
 Otherwise it returns 0.