r2716: created a separate detailed talloc_guide.txt document, after volker

complained it was all too confusing :-)

I recommend that everyone who wants to work on Samba4 have a read of this.
(This used to be commit c4c427576c02b27d829ae4aaee31cbf893b4a2ad)

1 files changed, 4 insertions, 57 deletions

diff --git a/prog_guide.txt b/prog_guide.txt
index 4bf8671e60..31a9fb8861 100644
--- a/prog_guide.txt
+++ b/prog_guide.txt
@@ -191,54 +191,8 @@ in the data and bss columns in "size" anyway (it will be included in
 How to use talloc
 -----------------
 
-If you are used to talloc from Samba3 then please read this carefully,
-as talloc has changed rather a lot.
-
-The new talloc is a hierarchical, reference counted memory pool system
-with destructors. Quite a mounthful really, but not too bad once you
-get used to it.
-
-Perhaps the biggest change from Samba3 is that there is no distinction
-between a "talloc context" and a "talloc pointer". Any pointer
-returned from talloc() is itself a valid talloc context. This means
-you can do this:
-
-  struct foo *a = talloc(mem_ctx, sizeof(*s));
-  a->name = talloc(a, strlen("foo")+1);
-
-and the pointer a->name would be a "child" of the talloc context "a"
-which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
-then it is all destroyed, whereas if you do talloc_free(a) then just a
-and a->name are destroyed.
-
-If you think about this, then what this effectively gives you is an
-n-ary tree, where you can free any part of the tree with
-talloc_free().
-
-The next big change with the new talloc is reference counts. A talloc
-pointer starts with a reference count of 1. You can call
-talloc_increase_ref_count() on any talloc pointer and that increases
-the reference count by 1. If you then call talloc_free() on a pointer
-that has a reference count greater than 1, then the reference count is
-decreased, but the memory is not released.
-
-Finally, talloc now has destructors. You can set a destructor on any
-talloc pointer using talloc_set_destructor(). Your destructor will
-then be called before the memory is released. An interesting feature
-of these destructors is that they can return a error. If the
-destructor returns -1 then that is interpreted as a refusal to release
-the memory, and the talloc_free() will return. It will also prevent
-the release of all memory "below" that memory in the tree.
-
-You should also go and look at a new talloc function in Samba4 called
-talloc_steal(). By using talloc_steal() you can move a lump of memory
-from one memory context to another without copying the data. This
-should be used when a backend function (such as a packet parser)
-produces a result as a lump of talloc memory and you need to keep it
-around for a longer lifetime than the talloc context it is in. You
-just "steal" the memory from the short-lived context, putting it into
-your long lived context.
-
+Please see the separate document, talloc_guide.txt in this
+directory. You _must_ read this if you want to program in Samba4.
 
 Interface Structures
 --------------------
@@ -583,9 +537,11 @@ other recognised flags are:
 
   sign : enable ntlmssp signing
   seal : enable ntlmssp sealing
+  connect : enable rpc connect level auth (auth, but no sign or seal)
   validate: enable the NDR validator
   print: enable debugging of the packets
   bigendian: use bigendian RPC
+  padcheck: check reply data for non-zero pad bytes
 
 
 For example, these all connect to the samr pipe:
@@ -645,8 +601,6 @@ MSRPC
  - msrpc
 
 
-- use _p talloc varients
-
 don't zero structures! avoid ZERO_STRUCT() and talloc_zero()
 
 
@@ -656,8 +610,6 @@ put in full UNC path in tconx
 
 test timezone handling by using a server in different zone from client
 
-don't just use any old TALLOC_CTX, use the right one!
-
 do {} while (0) system
 
 NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR()
@@ -665,8 +617,6 @@ NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR()
 need to implement secondary parts of trans2 and nttrans in server and
 client
 
-add talloc_steal() to move a talloc ptr from one pool to another
-
 document access_mask in openx reply
 
 check all capabilities and flag1, flag2 fields (eg. EAs)
@@ -803,7 +753,6 @@ Ideas
 
 
 BUGS:
-  non-signed non-sealed RPC (level == 2 == "connect")
   add a test case for last_entry_offset in trans2 find interfaces
   conn refused
   connect -> errno
@@ -814,5 +763,3 @@ BUGS:
      trans2 and other calls
   handle servers that don't have the setattre call in torture
   add max file coponent length test and max path len test
-
-