← Back to branch summary

~ubuntu-branches/ubuntu/vivid/samba/vivid

« back to all changes in this revision

Viewing changes to lib/talloc/doc/mainpage.dox

  • Committer: Package Import Robot
  • Author(s): Chuck Short
  • Date: 2011-12-21 13:18:04 UTC
  • mfrom: (0.39.21 sid)
  • Revision ID: package-import@ubuntu.com-20111221131804-xtlr39wx6njehxxr
Tags: 2:3.6.1-3ubuntu1
* Merge from Debian testing.  Remaining changes:
  + debian/patches/VERSION.patch:
    - set SAMBA_VERSION_SUFFIX to Ubuntu.
  + debian/patches/error-trans.fix-276472:
    - Add the translation of Unix Error code -ENOTSUP to NT Error Code
    - NT_STATUS_NOT_SUPPORTED to prevent the Permission denied error.
  + debian/smb.conf:
    - add "(Samba, Ubuntu)" to server string.
    - comment out the default [homes] share, and add a comment about
      "valid users = %S" to show users how to restrict access to
      \\server\username to only username.
    - Set 'usershare allow guests', so that usershare admins are 
      allowed to create public shares in addition to authenticated
      ones.
    - add map to guest = Bad user, maps bad username to guest access.
  + debian/samba-common.config:
    - Do not change priority to high if dhclient3 is installed.
    - Use priority medium instead of high for the workgroup question.
  + debian/control:
    - Don't build against or suggest ctdb.
    - Add dependency on samba-common-bin to samba.
  + Add ufw integration:
    - Created debian/samba.ufw.profile
    - debian/rules, debian/samba.dirs, debian/samba.files: install
      profile
    - debian/control: have samba suggest ufw
  + Add apport hook:
    - Created debian/source_samba.py.
    - debian/rules, debian/samba.dirs, debian/samba-common-bin.files: install
  + Switch to upstart:
    - Add debian/samba.{nmbd,smbd}.upstart.
  + debian/samba.logrotate, debian/samba-common.dhcp, debian/samba.if-up:
    - Make them upstart compatible
  + debian/samba.postinst: 
    - Avoid scary pdbedit warnings on first import.
  + debian/samba-common.postinst: Add more informative error message for
    the case where smb.conf was manually deleted
  + debian/patches/fix-debuglevel-name-conflict.patch: don't use 'debug_level'
    as a global variable name in an NSS module 
  + Dropped:
    - debian/patches/error-trans.fix-276472
    - debian/patches/fix-debuglevel-name-conflict.patch

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/talloc/doc/mainpage.dox
 
1
/**
 
2
 * @mainpage
 
3
 *
 
4
 * talloc is a hierarchical, reference counted memory pool system with
 
5
 * destructors. It is the core memory allocator used in Samba.
 
6
 *
 
7
 * @section talloc_download Download
 
8
 *
 
9
 * You can download the latest releases of talloc from the
 
10
 * <a href="http://samba.org/ftp/talloc" target="_blank">talloc directory</a>
 
11
 * on the samba public source archive.
 
12
 *
 
13
 * @section talloc_bugs Discussion and bug reports
 
14
 *
 
15
 * talloc does not currently have its own mailing list or bug tracking system.
 
16
 * For now, please use the
 
17
 * <a href="https://lists.samba.org/mailman/listinfo/samba-technical" target="_blank">samba-technical</a>
 
18
 * mailing list, and the
 
19
 * <a href="http://bugzilla.samba.org/" target="_blank">Samba bugzilla</a>
 
20
 * bug tracking system.
 
21
 *
 
22
 * @section talloc_devel Development
 
23
 * You can download the latest code either via git or rsync.
 
24
 *
 
25
 * To fetch via git see the following guide:
 
26
 *
 
27
 * <a href="http://wiki.samba.org/index.php/Using_Git_for_Samba_Development" target="_blank">Using Git for Samba Development</a>
 
28
 *
 
29
 * Once you have cloned the tree switch to the master branch and cd into the
 
30
 * lib/tevent directory.
 
31
 *
 
32
 * To fetch via rsync use this command:
 
33
 *
 
34
 * rsync -Pavz samba.org::ftp/unpacked/standalone_projects/lib/talloc .
 
35
 *
 
36
 * @section talloc_preample Preamble
 
37
 *
 
38
 * talloc is a hierarchical, reference counted memory pool system with
 
39
 * destructors.
 
40
 *
 
41
 * Perhaps the biggest difference from other memory pool systems is that there
 
42
 * is no distinction between a "talloc context" and a "talloc pointer". Any
 
43
 * pointer returned from talloc() is itself a valid talloc context. This means
 
44
 * you can do this:
 
45
 *
 
46
 * @code
 
47
 *      struct foo *X = talloc(mem_ctx, struct foo);
 
48
 *      X->name = talloc_strdup(X, "foo");
 
49
 * @endcode
 
50
 *
 
51
 * The pointer X->name would be a "child" of the talloc context "X" which is
 
52
 * itself a child of mem_ctx. So if you do talloc_free(mem_ctx) then it is all
 
53
 * destroyed, whereas if you do talloc_free(X) then just X and X->name are
 
54
 * destroyed, and if you do talloc_free(X->name) then just the name element of
 
55
 * X is destroyed.
 
56
 *
 
57
 * If you think about this, then what this effectively gives you is an n-ary
 
58
 * tree, where you can free any part of the tree with talloc_free().
 
59
 *
 
60
 * If you find this confusing, then run the testsuite to watch talloc in
 
61
 * action. You may also like to add your own tests to testsuite.c to clarify
 
62
 * how some particular situation is handled.
 
63
 *
 
64
 * @section talloc_performance Performance
 
65
 *
 
66
 * All the additional features of talloc() over malloc() do come at a price. We
 
67
 * have a simple performance test in Samba4 that measures talloc() versus
 
68
 * malloc() performance, and it seems that talloc() is about 4% slower than
 
69
 * malloc() on my x86 Debian Linux box. For Samba, the great reduction in code
 
70
 * complexity that we get by using talloc makes this worthwhile, especially as
 
71
 * the total overhead of talloc/malloc in Samba is already quite small.
 
72
 *
 
73
 * @section talloc_named Named blocks
 
74
 *
 
75
 * Every talloc chunk has a name that can be used as a dynamic type-checking
 
76
 * system. If for some reason like a callback function you had to cast a
 
77
 * "struct foo *" to a "void *" variable, later you can safely reassign the
 
78
 * "void *" pointer to a "struct foo *" by using the talloc_get_type() or
 
79
 * talloc_get_type_abort() macros.
 
80
 *
 
81
 * @code
 
82
 *      struct foo *X = talloc_get_type_abort(ptr, struct foo);
 
83
 * @endcode
 
84
 *
 
85
 * This will abort if "ptr" does not contain a pointer that has been created
 
86
 * with talloc(mem_ctx, struct foo).
 
87
 *
 
88
 * @section talloc_threading Multi-threading
 
89
 *
 
90
 * talloc itself does not deal with threads. It is thread-safe (assuming the
 
91
 * underlying "malloc" is), as long as each thread uses different memory
 
92
 * contexts.
 
93
 *
 
94
 * If two threads uses the same context then they need to synchronize in order
 
95
 * to be safe. In particular:
 
96
 *
 
97
 *   - when using talloc_enable_leak_report(), giving directly NULL as a parent
 
98
 *     context implicitly refers to a hidden "null context" global variable, so
 
99
 *     this should not be used in a multi-threaded environment without proper
 
100
 *     synchronization.
 
101
 *   - the context returned by talloc_autofree_context() is also global so
 
102
 *     shouldn't be used by several threads simultaneously without
 
103
 *     synchronization.
 
104
 *
 
105
 */