diff options
Diffstat (limited to 'erts')
| -rw-r--r-- | erts/aclocal.m4 | 5 | ||||
| -rw-r--r-- | erts/doc/src/erl.xml | 45 | ||||
| -rw-r--r-- | erts/doc/src/erl_driver.xml | 7 | ||||
| -rw-r--r-- | erts/doc/src/erl_nif.xml | 78 | ||||
| -rw-r--r-- | erts/doc/src/erlang.xml | 72 | ||||
| -rw-r--r-- | erts/doc/src/erts_alloc.xml | 164 |
6 files changed, 170 insertions, 201 deletions
diff --git a/erts/aclocal.m4 b/erts/aclocal.m4 index 8052b2d67d..3d935b7295 100644 --- a/erts/aclocal.m4 +++ b/erts/aclocal.m4 @@ -826,8 +826,11 @@ case "$THR_LIB_NAME" in AC_CHECK_FUNC(pthread_spin_lock, \ AC_DEFINE(ETHR_HAVE_PTHREAD_SPIN_LOCK, 1, \ [Define if you have the pthread_spin_lock function.])) + test "$force_linux_pthread_rwlocks" = "yes" || { + force_linux_pthread_rwlocks=no + } case "$force_linux_pthread_rwlocks-$host_os" in - yes-linux*) # Writers may get starved + no-linux*) # Writers may get starved # TODO: write a test that tests the implementation ;; *) diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index 7a2ab375d1..bb741c7836 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -131,9 +131,8 @@ see <seealso marker="kernel:app">app(4)</seealso> and <seealso marker="kernel:application">application(3)</seealso>.</p> </item> - <tag><c><![CDATA[-args_file FileName]]></c></tag> + <tag><marker id="args_file"><c><![CDATA[-args_file FileName]]></c></marker></tag> <item> - <marker id="args_file"></marker> <p>Command line arguments are read from the file <c><![CDATA[FileName]]></c>. The arguments read from the file replace the '<c><![CDATA[-args_file FileName]]></c>' flag on the resulting command line.</p> @@ -197,9 +196,8 @@ <seealso marker="kernel:app">app(4)</seealso> and <seealso marker="kernel:application">application(3)</seealso>.</p> </item> - <tag><c><![CDATA[-connect_all false]]></c></tag> + <tag><marker id="connect_all"><c><![CDATA[-connect_all false]]></c></marker></tag> <item> - <marker id="connect_all"></marker> <p>If this flag is present, <c><![CDATA[global]]></c> will not maintain a fully connected network of distributed Erlang nodes, and then global name registration cannot be used. See @@ -282,9 +280,8 @@ <p>Makes <c><![CDATA[init]]></c> write some debug information while interpreting the boot script.</p> </item> - <tag><c><![CDATA[-instr]]></c>(emulator flag)</tag> + <tag><marker id="instr"><c><![CDATA[-instr]]></c>(emulator flag)</marker></tag> <item> - <marker id="instr"></marker> <p>Selects an instrumented Erlang runtime system (virtual machine) to run, instead of the ordinary one. When running an instrumented runtime system, some resource usage data can be @@ -431,9 +428,8 @@ flag and those running with the <c><![CDATA[-name]]></c> flag, as node names must be unique in distributed Erlang systems.</p> </item> - <tag><c><![CDATA[-smp [enable|auto|disable]]]></c></tag> + <tag><marker id="smp"><c><![CDATA[-smp [enable|auto|disable]]]></c></marker></tag> <item> - <marker id="smp"></marker> <p><c>-smp enable</c> and <c>-smp</c> starts the Erlang runtime system with SMP support enabled. This may fail if no runtime system with SMP support is available. <c>-smp auto</c> starts @@ -462,9 +458,8 @@ <p><c><![CDATA[erl]]></c> invokes the code for the Erlang emulator (virtual machine), which supports the following flags:</p> <taglist> - <tag><c><![CDATA[+a size]]></c></tag> + <tag><marker id="async_thread_stack_size"><c><![CDATA[+a size]]></c></marker></tag> <item> - <marker id="async_thread_stack_size"></marker> <p>Suggested stack size, in kilowords, for threads in the async-thread pool. Valid range is 16-8192 kilowords. The default suggested stack size is 16 kilowords, i.e, 64 @@ -478,9 +473,8 @@ suggestion, and it might even be ignored on some platforms.</p> </item> - <tag><c><![CDATA[+A size]]></c></tag> + <tag><marker id="async_thread_pool_size"><c><![CDATA[+A size]]></c></marker></tag> <item> - <marker id="async_thread_pool_size"></marker> <p>Sets the number of threads in async thread pool, valid range is 0-1024. Default is 0.</p> </item> @@ -550,23 +544,20 @@ <p>Enables auto load tracing, displaying info while loading code.</p> </item> - <tag><c><![CDATA[+MFlag Value]]></c></tag> + <tag><marker id="erts_alloc"><c><![CDATA[+MFlag Value]]></c></marker></tag> <item> - <marker id="erts_alloc"></marker> <p>Memory allocator specific flags, see <seealso marker="erts_alloc">erts_alloc(3)</seealso> for further information.</p> </item> - <tag><c><![CDATA[+P Number]]></c></tag> + <tag><marker id="max_processes"><c><![CDATA[+P Number]]></c></marker></tag> <item> - <marker id="max_processes"></marker> <p>Sets the maximum number of concurrent processes for this system. <c><![CDATA[Number]]></c> must be in the range 16..134217727. Default is 32768.</p> </item> - <tag><c><![CDATA[+R ReleaseNumber]]></c></tag> + <tag><marker id="compat_rel"><c><![CDATA[+R ReleaseNumber]]></c></marker></tag> <item> - <marker id="compat_rel"></marker> <p>Sets the compatibility mode.</p> <p>The distribution mechanism is not backwards compatible by default. This flags sets the emulator in compatibility mode @@ -592,9 +583,8 @@ <item> <p>Force ets memory block to be moved on realloc.</p> </item> - <tag><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></tag> + <tag><marker id="+S"><c><![CDATA[+S Schedulers:SchedulerOnline]]></c></marker></tag> <item> - <marker id="+S"></marker> <p>Sets the amount of scheduler threads to create and scheduler threads to set online when SMP support has been enabled. Valid range for both values are 1-1024. If the @@ -615,9 +605,8 @@ <item> <p>Scheduling specific flags.</p> <taglist> - <tag>+sbt BindType</tag> + <tag><marker id="+sbt"><c>+sbt BindType</c></marker></tag> <item> - <marker id="+sbt"></marker> <p>Set scheduler bind type. Currently valid <c>BindType</c>s: </p> <taglist> @@ -672,9 +661,8 @@ <seealso marker="erlang#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, SchedulerBindType)</seealso>. </p> </item> - <tag><c>+sct CpuTopology</c></tag> + <tag><marker id="+sct"><c>+sct CpuTopology</c></marker></tag> <item> - <marker id="+sct"></marker> <list type="bulleted"> <item><c><![CDATA[<Id> = integer(); when 0 =< <Id> =< 65535]]></c></item> <item><c><![CDATA[<IdRange> = <Id>-<Id>]]></c></item> @@ -791,21 +779,18 @@ </item> </taglist> </item> - <tag><c><![CDATA[+sss size]]></c></tag> + <tag><marker id="sched_thread_stack_size"><c><![CDATA[+sss size]]></c></marker></tag> <item> - <marker id="sched_thread_stack_size"></marker> <p>Suggested stack size, in kilowords, for scheduler threads. Valid range is 4-8192 kilowords. The default stack size is OS dependent.</p> </item> - <tag><c><![CDATA[+t size]]></c></tag> + <tag><marker id="+t"><c><![CDATA[+t size]]></c></marker></tag> <item> - <marker id="+t"></marker> <p>Set the maximum number of atoms the VM can handle. Default is 1048576.</p> </item> - <tag><c><![CDATA[+T Level]]></c></tag> + <tag><marker id="+T"><c><![CDATA[+T Level]]></c></marker></tag> <item> - <marker id="+T"></marker> <p>Enables modified timing and sets the modified timing level. Currently valid range is 0-9. The timing of the runtime system will change. A high level usually means a greater change than diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 63108f41f0..5061230a33 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -171,8 +171,8 @@ asynchronous function calls, using a thread pool provided by Erlang. There is also a select call, that can be used for asynchronous drivers.</item> - <tag>Multi-threading</tag> - <item><marker id="multi_threading"></marker> + <tag><marker id="multi_threading">Multi-threading</marker></tag> + <item> <p>A POSIX thread like API for multi-threading is provided. The Erlang driver thread API only provide a subset of the functionality provided by the POSIX thread API. The subset provided is @@ -245,9 +245,8 @@ <item>A driver can add and later remove drivers.</item> <tag>Monitoring processes</tag> <item>A driver can monitor a process that does not own a port.</item> - <tag>Version management</tag> + <tag><marker id="version_management">Version management</marker></tag> <item> - <marker id="version_management"></marker> <p>Version management is enabled for drivers that have set the <seealso marker="driver_entry#extended_marker">extended_marker</seealso> field of their diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index d25c63be3d..2e55f13ed5 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -115,7 +115,7 @@ ok </note> <p>A loaded NIF library is tied to the Erlang module code version that loaded it. If the module is upgraded with a new version, the - new code will have to load its own NIF library (or maybe choose not + new Erlang code will have to load its own NIF library (or maybe choose not to). The new code version can however choose to load the exact same NIF library as the old code if it wants to. Sharing the same dynamic library will mean that static data defined by the library @@ -146,7 +146,8 @@ ok to query terms, like <c>enif_is_atom</c>, <c>enif_is_identical</c> and <c>enif_compare</c>.</p></item> <tag>Binaries</tag> - <item><p>Terms of type binary are accessed through the struct type <seealso marker="#ErlNifBinary">ErlNifBinary</seealso> + <item><p>Terms of type binary are accessed with the help of the struct type + <seealso marker="#ErlNifBinary">ErlNifBinary</seealso> that contains a pointer (<c>data</c>) to the raw binary data and the length (<c>size</c>) of the data in bytes. Both <c>data</c> and <c>size</c> are read-only and should only be written using calls to API functions. @@ -155,17 +156,20 @@ ok <p>The raw data pointed to by <c>data</c> is only mutable after a call to <seealso marker="#enif_alloc_binary">enif_alloc_binary</seealso>. All other functions that operates on a binary will leave the data as read-only. - An allocated binary must in the end either be freed with - <seealso marker="#enif_release_binary">enif_release_binary</seealso> - or transferred to an Erlang term with <seealso marker="#enif_make_binary">enif_make_binary</seealso>. - But it does not have do happen in the same NIF call.</p> - <p>Binaries must be a number of whole bytes. Bitstrings with an arbitrary + A mutable binary allocated with <c>enif_alloc_binary</c> must in the end + either be freed with <seealso marker="#enif_release_binary">enif_release_binary</seealso> + or made read-only by transferring it to an Erlang term with + <seealso marker="#enif_make_binary">enif_make_binary</seealso>. + But it does not have do happen in the same NIF call. Read-only binaries + does not have to be released.</p> + <p>Binaries are sequences of whole bytes. Bitstrings with an arbitrary bit length have no support yet.</p> </item> <tag>Resource objects</tag> - <item><p>Resource objects are a way to return pointers to native data - structures from a NIF in a safe way. A resource object is just a block - of memory allocated with <seealso marker="#enif_alloc_resource">enif_alloc_resource()</seealso>. + <item><p>The use of resource objects is a way to return pointers to + native data structures from a NIF in a safe way. A resource object is + just a block of memory allocated with + <seealso marker="#enif_alloc_resource">enif_alloc_resource()</seealso>. A handle ("safe pointer") to this memory block can then be returned to Erlang by the use of <seealso marker="#enif_make_resource">enif_make_resource()</seealso>. The term returned by <c>enif_make_resource</c> @@ -178,20 +182,46 @@ ok released with <seealso marker="#enif_release_resource">enif_release_resource()</seealso> (not necessarily in that order).</p> <p>All resource objects are created as instances of some <em>resource type</em>. - This makes resources from different modules or applications to be distinguishable. + This makes resources from different modules to be distinguishable. A resource type is created by calling <seealso marker="#enif_open_resource_type">enif_open_resource_type()</seealso> when a library is loaded. Objects of that resource type can then later be allocated and <c>enif_get_resource</c> verifies that the resource is of the expected type. - A resource type can have a destructor function that is automatically - called when resources of that type are released (by either the garbage - collector or <c>enif_release_resource</c>). Resource types also support - upgrade in runtime by allowing a loaded NIF library to takeover an already - existing resource type and thereby "inherit" all existing objects of that type. - The destructor of the new library will thereafter be called for the inherited - objects and the library with the old destructor function can be safely - unloaded. Resource types are uniquely identified by a supplied name string. + A resource type can have a user supplied destructor function that is + automatically called when resources of that type are released (by either + the garbage collector or <c>enif_release_resource</c>). Resource types + are uniquely identified by a supplied name string.</p> + <p>Resource types support upgrade in runtime by allowing a loaded NIF + library to takeover an already existing resource type and thereby + "inherit" all existing objects of that type. The destructor of the new + library will thereafter be called for the inherited objects and the + library with the old destructor function can be safely unloaded. Existing + resource objects, of a module that is upgraded, must either be deleted + or taken over by the new NIF library. The unloading of a library will be + postponed as long as it exists resource objects with a destructor + function in the library. </p> + <p>Here is a template example of how to create and return a resource object.</p> + <p/> + <code type="none"> + ERL_NIF_TERM term; + MyStruct* ptr = enif_alloc_resource(env, my_resource_type, sizeof(MyStruct)); + + /* initialize struct ... */ + + term = enif_make_resource(env, ptr); + + if (keep_a_reference_of_our_own) { + /* store 'ptr' in static variable, private data or other resource object */ + } + else { + enif_release_resource(env, obj); + /* resource now only owned by "Erlang" */ + } + return term; +} +</code> + </item> <tag>Threads and concurrency</tag> <item><p>A NIF is thread-safe without any explicit synchronization as @@ -232,7 +262,9 @@ ok and there is no previously loaded library for this module.</p> <p><c>*priv_data</c> can be set to point to some private data that the library needs in able to keep a state between NIF - calls. <c>enif_priv_data()</c> will return this pointer.</p> + calls. <c>enif_priv_data()</c> will return this pointer. + <c>*priv_data</c> will be initialized to NULL when <c>load</c> is + called.</p> <p><c>load_info</c> is the second argument to <seealso marker="erlang#load_nif-2">erlang:load_nif/2</seealso>.</p> <p>The library will fail to load if <c>load</c> returns @@ -258,7 +290,8 @@ ok <p>Works the same as <c>load</c>. The only difference is that <c>*old_priv_data</c> already contains the value set by the last call to <c>load</c> or <c>reload</c> for the old module - code. It is allowed to write to both *priv_data and *old_priv_data.</p> + code. <c>*priv_data</c> will be initialized to NULL when <c>upgrade</c> + is called. It is allowed to write to both *priv_data and *old_priv_data.</p> <p>The library will fail to load if <c>upgrade</c> returns anything other than 0 or if <c>upgrade</c> is NULL.</p> </item> @@ -266,7 +299,8 @@ ok <tag><marker id="unload"/>void (*unload)(ErlNifEnv* env, void* priv_data)</tag> <item><p><c>unload</c> is called when the module code that the NIF library belongs to is purged as old. New code - of the same module may or may not exist.</p> + of the same module may or may not exist. Note that <c>unload</c> is not + called for a replaced library as a consequence of <c>reload</c>.</p> </item> </taglist> diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index d4fd8c8c9f..46f8df4683 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -3474,9 +3474,8 @@ os_prompt%</pre> <p>This changes the minimum binary virtual heap size for the calling process.</p> </item> - <tag><c>process_flag(priority, Level)</c></tag> + <tag><marker id="process_flag_priority"><c>process_flag(priority, Level)</c></marker></tag> <item> - <marker id="process_flag_priority"></marker> <p>This sets the process priority. <c>Level</c> is an atom. There are currently four priority levels: <c>low</c>, <c>normal</c>, <c>high</c>, and <c>max</c>. The default @@ -4788,9 +4787,8 @@ true</pre> <c>ContextSwitches</c> is the total number of context switches since the system started.</p> </item> - <tag><c>exact_reductions</c></tag> + <tag><marker id="statistics_exact_reductions"><c>exact_reductions</c></marker></tag> <item> - <marker id="statistics_exact_reductions"></marker> <p>Returns <c>{Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}</c>.</p> <p><em>NOTE:</em><c>statistics(exact_reductions)</c> is @@ -4810,9 +4808,8 @@ true</pre> through ports, and <c>Output</c> is the total number of bytes output to ports.</p> </item> - <tag><c>reductions</c></tag> + <tag><marker id="statistics_reductions"><c>reductions</c></marker></tag> <item> - <marker id="statistics_reductions"></marker> <p>Returns <c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p> <p><em>NOTE:</em> From erts version 5.5 (OTP release R11B) @@ -4983,9 +4980,8 @@ true</pre> <p>Sets the maximum depth of call stack back-traces in the exit reason element of <c>'EXIT'</c> tuples.</p> </item> - <tag><c>erlang:system_flag(cpu_topology, CpuTopology)</c></tag> + <tag><marker id="system_flag_cpu_topology"><c>erlang:system_flag(cpu_topology, CpuTopology)</c></marker></tag> <item> - <marker id="system_flag_cpu_topology"></marker> <p>Sets the user defined <c>CpuTopology</c>. The user defined CPU topology will override any automatically detected CPU topology. By passing <c>undefined</c> as <c>CpuTopology</c> @@ -5047,9 +5043,8 @@ true</pre> <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or <seealso marker="#process_flag/2">process_flag/2</seealso>. </p> </item> - <tag><c>erlang:system_flag(multi_scheduling, BlockState)</c></tag> + <tag><marker id="system_flag_multi_scheduling"><c>erlang:system_flag(multi_scheduling, BlockState)</c></marker></tag> <item> - <marker id="system_flag_multi_scheduling"></marker> <p><c>BlockState = block | unblock</c></p> <p>If multi-scheduling is enabled, more than one scheduler thread is used by the emulator. Multi-scheduling can be @@ -5083,9 +5078,8 @@ true</pre> <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><c>erlang:system_flag(scheduler_bind_type, How)</c></tag> + <tag><marker id="system_flag_scheduler_bind_type"><c>erlang:system_flag(scheduler_bind_type, How)</c></marker></tag> <item> - <marker id="system_flag_scheduler_bind_type"></marker> <p>Controls if and how schedulers are bound to logical processors.</p> <p>When <c>erlang:system_flag(scheduler_bind_type, How)</c> is @@ -5212,9 +5206,8 @@ true</pre> <seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>. </p> </item> - <tag><c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></tag> + <tag><marker id="system_flag_schedulers_online"><c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></marker></tag> <item> - <marker id="system_flag_schedulers_online"></marker> <p>Sets the amount of schedulers online. Valid range is <![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]>. </p> @@ -5252,9 +5245,8 @@ true</pre> <p>Returns various information about the current system (emulator) as specified by <c>Type</c>:</p> <taglist> - <tag><c>allocated_areas</c></tag> + <tag><marker id="system_info_allocated_areas"><c>allocated_areas</c></marker></tag> <item> - <marker id="system_info_allocated_areas"></marker> <p>Returns a list of tuples with information about miscellaneous allocated memory areas.</p> <p>Each tuple contains an atom describing type of memory as @@ -5274,9 +5266,8 @@ true</pre> in the total amount of memory allocated by the emulator see <seealso marker="#memory/0">erlang:memory/0,1</seealso>.</p> </item> - <tag><c>allocator</c></tag> + <tag><marker id="system_info_allocator"><c>allocator</c></marker></tag> <item> - <marker id="system_info_allocator"></marker> <p>Returns <c>{Allocator, Version, Features, Settings}.</c></p> <p>Types:</p> <list type="bulleted"> @@ -5317,9 +5308,8 @@ true</pre> <p>See also "System Flags Effecting erts_alloc" in <seealso marker="erts:erts_alloc#flags">erts_alloc(3)</seealso>.</p> </item> - <tag><c>alloc_util_allocators</c></tag> + <tag><marker id="system_info_alloc_util_allocators"><c>alloc_util_allocators</c></marker></tag> <item> - <marker id="system_info_alloc_util_allocators"></marker> <p>Returns a list of the names of all allocators using the ERTS internal <c>alloc_util</c> framework as atoms. For more information see the @@ -5328,9 +5318,8 @@ true</pre> erts_alloc(3)</seealso> documentation. </p> </item> - <tag><c>{allocator, Alloc}</c></tag> + <tag><marker id="system_info_allocator_tuple"><c>{allocator, Alloc}</c></marker></tag> <item> - <marker id="system_info_allocator_tuple"></marker> <p>Returns information about the specified allocator. As of erts version 5.6.1 the return value is a list of <c>{instance, InstanceNo, InstanceInfo}</c> tuples @@ -5366,9 +5355,8 @@ true</pre> values. The first value is memory pool size and the second value used memory size.</p> </item> - <tag><c>{allocator_sizes, Alloc}</c></tag> + <tag><marker id="system_info_allocator_sizes"><c>{allocator_sizes, Alloc}</c></marker></tag> <item> - <marker id="system_info_allocator_sizes"></marker> <p>Returns various size information for the specified allocator. The information returned is a subset of the information returned by @@ -5402,9 +5390,8 @@ true</pre> line flag <c>+R</c>, see <seealso marker="erts:erl#compat_rel">erl(1)</seealso>.</p> </item> - <tag><c>cpu_topology</c></tag> + <tag><marker id="system_info_cpu_topology"><c>cpu_topology</c></marker></tag> <item> - <marker id="system_info_cpu_topology"></marker> <p>Returns the <c>CpuTopology</c> which currently is used by the emulator. The CPU topology is used when binding schedulers to logical processors. The CPU topology used is the user defined @@ -5677,9 +5664,8 @@ true</pre> <seealso marker="erts:erl#+T">erl(1)</seealso> command for more information on modified timing.</p> </item> - <tag><c>multi_scheduling</c></tag> + <tag><marker id="system_info_multi_scheduling"><c>multi_scheduling</c></marker></tag> <item> - <marker id="system_info_multi_scheduling"></marker> <p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>. A description of the return values:</p> <taglist> @@ -5708,9 +5694,8 @@ true</pre> <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><c>multi_scheduling_blockers</c></tag> + <tag><marker id="system_info_multi_scheduling_blockers"><c>multi_scheduling_blockers</c></marker></tag> <item> - <marker id="system_info_multi_scheduling_blockers"></marker> <p>Returns a list of <c>PID</c>s when multi-scheduling is blocked; otherwise, the empty list. The <c>PID</c>s in the list is <c>PID</c>s of the processes currently @@ -5721,9 +5706,8 @@ true</pre> <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><c>otp_release</c></tag> + <tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag> <item> - <marker id="system_info_otp_release"></marker> <p>Returns a string containing the OTP release number.</p> </item> <tag><c>process_count</c></tag> @@ -5747,9 +5731,8 @@ true</pre> information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS User's Guide.</p> </item> - <tag><c>scheduler_bind_type</c></tag> + <tag><marker id="system_info_scheduler_bind_type"><c>scheduler_bind_type</c></marker></tag> <item> - <marker id="system_info_scheduler_bind_type"></marker> <p>Returns information on how user has requested schedulers to be bound or not bound.</p> <p><em>NOTE:</em> Even though user has requested @@ -5764,9 +5747,8 @@ true</pre> <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>. </p> </item> - <tag><c>scheduler_bindings</c></tag> + <tag><marker id="system_info_scheduler_bindings"><c>scheduler_bindings</c></marker></tag> <item> - <marker id="system_info_scheduler_bindings"></marker> <p>Returns information on currently used scheduler bindings.</p> <p>A tuple of a size equal to @@ -5788,18 +5770,16 @@ true</pre> <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>. </p> </item> - <tag><c>scheduler_id</c></tag> + <tag><marker id="system_info_scheduler_id"><c>scheduler_id</c></marker></tag> <item> - <marker id="system_info_scheduler_id"></marker> <p>Returns the scheduler id (<c>SchedulerId</c>) of the scheduler thread that the calling process is executing on. <c>SchedulerId</c> is a positive integer; where <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. See also <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p> </item> - <tag><c>schedulers</c></tag> + <tag><marker id="system_info_schedulers"><c>schedulers</c></marker></tag> <item> - <marker id="system_info_schedulers"></marker> <p>Returns the number of scheduler threads used by the emulator. Scheduler threads online schedules Erlang processes and Erlang ports, and execute Erlang code @@ -5815,9 +5795,8 @@ true</pre> <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and and <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p> </item> - <tag><c>schedulers_online</c></tag> + <tag><marker id="system_info_schedulers_online"><c>schedulers_online</c></marker></tag> <item> - <marker id="system_info_schedulers_online"></marker> <p>Returns the amount of schedulers online. The scheduler identifiers of schedulers online satisfy the following relationship: @@ -5850,9 +5829,8 @@ true</pre> with thread support; otherwise, <c>false</c> is returned.</p> </item> - <tag><c>thread_pool_size</c></tag> + <tag><marker id="system_info_thread_pool_size"><c>thread_pool_size</c></marker></tag> <item> - <marker id="system_info_thread_pool_size"></marker> <p>Returns the number of async threads in the async thread pool used for asynchronous driver calls (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>) @@ -5865,9 +5843,8 @@ true</pre> <c>get_tcw</c> in "Match Specifications in Erlang", <seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p> </item> - <tag><c>version</c></tag> + <tag><marker id="system_info_version"><c>version</c></marker></tag> <item> - <marker id="system_info_version"></marker> <p>Returns a string containing the version number of the emulator.</p> </item> @@ -6477,9 +6454,8 @@ true</pre> the current function cannot be determined, then the last element <c>Arity</c> is 0.</p> </item> - <tag><c>{trace, Pid, gc_start, Info}</c></tag> + <tag><marker id="gc_start"><c>{trace, Pid, gc_start, Info}</c></marker></tag> <item> - <marker id="gc_start"></marker> <p>Sent when garbage collection is about to be started. <c>Info</c> is a list of two-element tuples, where the first element is a key, and the second is the value. diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml index d51e5b3ea4..51a4a2bca0 100644 --- a/erts/doc/src/erts_alloc.xml +++ b/erts/doc/src/erts_alloc.xml @@ -4,7 +4,7 @@ <cref> <header> <copyright> - <year>2002</year><year>2009</year> + <year>2002</year><year>2010</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -13,12 +13,12 @@ compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. - + Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. - + </legalnotice> <title>erts_alloc</title> @@ -122,7 +122,7 @@ size (<seealso marker="#M_lmbcs">lmbcs</seealso>), the smallest multiblock carrier size (<seealso marker="#M_smbcs">smbcs</seealso>), and the multiblock carrier growth stages - (<seealso marker="#M_smbcs">mbcgs</seealso>) parameters. If + (<seealso marker="#M_mbcgs">mbcgs</seealso>) parameters. If <c>nc</c> is the current number of multiblock carriers (the main multiblock carrier excluded) managed by an allocator, the size of the next <c>mseg_alloc</c> multiblock carrier allocated by @@ -229,29 +229,25 @@ <p>The following flags are available for configuration of <c>mseg_alloc</c>:</p> <taglist> - <tag><c><![CDATA[+MMamcbf <size>]]></c></tag> - <item> <marker id="MMamcbf"></marker> - + <tag><marker id="MMamcbf"><c><![CDATA[+MMamcbf <size>]]></c></marker></tag> + <item> Absolute max cache bad fit (in kilobytes). A segment in the memory segment cache is not reused if its size exceeds the requested size with more than the value of this parameter. Default value is 4096. </item> - <tag><c><![CDATA[+MMrmcbf <ratio>]]></c></tag> - <item> <marker id="MMrmcbf"></marker> - + <tag><marker id="MMrmcbf"><c><![CDATA[+MMrmcbf <ratio>]]></c></marker></tag> + <item> Relative max cache bad fit (in percent). A segment in the memory segment cache is not reused if its size exceeds the requested size with more than relative max cache bad fit percent of the requested size. Default value is 20.</item> - <tag><c><![CDATA[+MMmcs <amount>]]></c></tag> - <item> <marker id="MMmcs"></marker> - + <tag><marker id="MMmcs"><c><![CDATA[+MMmcs <amount>]]></c></marker></tag> + <item> Max cached segments. The maximum number of memory segments stored in the memory segment cache. Valid range is 0-30. Default value is 5.</item> - <tag><c><![CDATA[+MMcci <time>]]></c></tag> - <item> <marker id="MMcci"></marker> - + <tag><marker id="MMcci"><c><![CDATA[+MMcci <time>]]></c></marker></tag> + <item> Cache check interval (in milliseconds). The memory segment cache is checked for segments to destroy at an interval determined by this parameter. Default value is 1000.</item> @@ -259,26 +255,23 @@ <p>The following flags are available for configuration of <c>fix_alloc</c>:</p> <taglist> - <tag><c>+MFe true</c></tag> - <item> <marker id="MFe"></marker> - + <tag><marker id="MFe"><c>+MFe true</c></marker></tag> + <item> Enable <c>fix_alloc</c>. Note: <c>fix_alloc</c> cannot be disabled.</item> </taglist> <p>The following flags are available for configuration of <c>sys_alloc</c>:</p> <taglist> - <tag><c>+MYe true</c></tag> - <item> <marker id="MYe"></marker> - + <tag><marker id="MYe"><c>+MYe true</c></marker></tag> + <item> Enable <c>sys_alloc</c>. Note: <c>sys_alloc</c> cannot be disabled.</item> - <tag><c>+MYm libc</c></tag> - <item> <marker id="MYm"></marker> -<c>malloc</c> library to use. Currently only + <tag><marker id="MYm"><c>+MYm libc</c></marker></tag> + <item> + <c>malloc</c> library to use. Currently only <c>libc</c> is available. <c>libc</c> enables the standard <c>libc</c> malloc implementation. By default <c>libc</c> is used.</item> - <tag><c><![CDATA[+MYtt <size>]]></c></tag> - <item> <marker id="MYtt"></marker> - + <tag><marker id="MYtt"><c><![CDATA[+MYtt <size>]]></c></marker></tag> + <item> Trim threshold size (in kilobytes). This is the maximum amount of free memory at the top of the heap (allocated by <c>sbrk</c>) that will be kept by <c>malloc</c> (not @@ -289,9 +282,8 @@ trim threshold is 128. <em>Note:</em> This flag will only have any effect when the emulator has been linked with the GNU C library, and uses its <c>malloc</c> implementation.</item> - <tag><c><![CDATA[+MYtp <size>]]></c></tag> - <item> <marker id="MYtp"></marker> - + <tag><marker id="MYtp"><c><![CDATA[+MYtp <size>]]></c></marker></tag> + <item> Top pad size (in kilobytes). This is the amount of extra memory that will be allocated by <c>malloc</c> when <c>sbrk</c> is called to get more memory from the operating @@ -308,43 +300,37 @@ subsystem identifier, only the specific allocator identified will be effected:</p> <taglist> - <tag><c><![CDATA[+M<S>as bf|aobf|gf|af]]></c></tag> - <item> <marker id="M_as"></marker> - + <tag><marker id="M_as"><c><![CDATA[+M<S>as bf|aobf|gf|af]]></c></marker></tag> + <item> Allocation strategy. Valid strategies are <c>bf</c> (best fit), <c>aobf</c> (address order best fit), <c>gf</c> (good fit), and <c>af</c> (a fit). See <seealso marker="#strategy">the description of allocation strategies</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><c><![CDATA[+M<S>asbcst <size>]]></c></tag> - <item> <marker id="M_asbcst"></marker> - + <tag><marker id="M_asbcst"><c><![CDATA[+M<S>asbcst <size>]]></c></marker></tag> + <item> Absolute singleblock carrier shrink threshold (in kilobytes). When a block located in an <c>mseg_alloc</c> singleblock carrier is shrunk, the carrier will be left unchanged if the amount of unused memory is less than this threshold; otherwise, the carrier will be shrunk. See also <seealso marker="#M_rsbcst">rsbcst</seealso>.</item> - <tag><c><![CDATA[+M<S>e true|false]]></c></tag> - <item> <marker id="M_e"></marker> - + <tag><marker id="M_e"><c><![CDATA[+M<S>e true|false]]></c></marker></tag> + <item> Enable allocator <c><![CDATA[<S>]]></c>.</item> - <tag><c><![CDATA[+M<S>lmbcs <size>]]></c></tag> - <item> <marker id="M_lmbcs"></marker> - + <tag><marker id="M_lmbcs"><c><![CDATA[+M<S>lmbcs <size>]]></c></marker></tag> + <item> Largest (<c>mseg_alloc</c>) multiblock carrier size (in kilobytes). See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><c><![CDATA[+M<S>mbcgs <ratio>]]></c></tag> - <item> <marker id="M_mbcgs"></marker> - + <tag><marker id="M_mbcgs"><c><![CDATA[+M<S>mbcgs <ratio>]]></c></marker></tag> + <item> (<c>mseg_alloc</c>) multiblock carrier growth stages. See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><c><![CDATA[+M<S>mbsd <depth>]]></c></tag> - <item> <marker id="M_mbsd"></marker> - + <tag><marker id="M_mbsd"><c><![CDATA[+M<S>mbsd <depth>]]></c></marker></tag> + <item> Max block search depth. This flag has effect only if the good fit strategy has been selected for allocator <c><![CDATA[<S>]]></c>. When the good fit strategy is used, free @@ -353,47 +339,41 @@ search depth sets a limit on the maximum number of blocks to inspect in a free list during a search for suitable block satisfying the request.</item> - <tag><c><![CDATA[+M<S>mmbcs <size>]]></c></tag> - <item> <marker id="M_mmbcs"></marker> - + <tag><marker id="M_mmbcs"><c><![CDATA[+M<S>mmbcs <size>]]></c></marker></tag> + <item> Main multiblock carrier size. Sets the size of the main multiblock carrier for allocator <c><![CDATA[<S>]]></c>. The main multiblock carrier is allocated via <c><![CDATA[sys_alloc]]></c> and is never deallocated.</item> - <tag><c><![CDATA[+M<S>mmmbc <amount>]]></c></tag> - <item> <marker id="M_mmmbc"></marker> - + <tag><marker id="M_mmmbc"><c><![CDATA[+M<S>mmmbc <amount>]]></c></marker></tag> + <item> Max <c>mseg_alloc</c> multiblock carriers. Maximum number of multiblock carriers allocated via <c>mseg_alloc</c> by allocator <c><![CDATA[<S>]]></c>. When this limit has been reached, new multiblock carriers will be allocated via <c>sys_alloc</c>.</item> - <tag><c><![CDATA[+M<S>mmsbc <amount>]]></c></tag> - <item> <marker id="M_mmsbc"></marker> - + <tag><marker id="M_mmsbc"><c><![CDATA[+M<S>mmsbc <amount>]]></c></marker></tag> + <item> Max <c>mseg_alloc</c> singleblock carriers. Maximum number of singleblock carriers allocated via <c>mseg_alloc</c> by allocator <c><![CDATA[<S>]]></c>. When this limit has been reached, new singleblock carriers will be allocated via <c>sys_alloc</c>.</item> - <tag><c><![CDATA[+M<S>ramv <bool>]]></c></tag> - <item> <marker id="M_ramv"></marker> - + <tag><marker id="M_ramv"><c><![CDATA[+M<S>ramv <bool>]]></c></marker></tag> + <item> Realloc always moves. When enabled, reallocate operations will more or less be translated into an allocate, copy, free sequence. This often reduce memory fragmentation, but costs performance. </item> - <tag><c><![CDATA[+M<S>rmbcmt <ratio>]]></c></tag> - <item> <marker id="M_rmbcmt"></marker> - + <tag><marker id="M_rmbcmt"><c><![CDATA[+M<S>rmbcmt <ratio>]]></c></marker></tag> + <item> Relative multiblock carrier move threshold (in percent). When a block located in a multiblock carrier is shrunk, the block will be moved if the ratio of the size of the returned memory compared to the previous size is more than this threshold; otherwise, the block will be shrunk at current location.</item> - <tag><c><![CDATA[+M<S>rsbcmt <ratio>]]></c></tag> - <item> <marker id="M_rsbcmt"></marker> - + <tag><marker id="M_rsbcmt"><c><![CDATA[+M<S>rsbcmt <ratio>]]></c></marker></tag> + <item> Relative singleblock carrier move threshold (in percent). When a block located in a singleblock carrier is shrunk to a size smaller than the value of the @@ -401,32 +381,28 @@ the block will be left unchanged in the singleblock carrier if the ratio of unused memory is less than this threshold; otherwise, it will be moved into a multiblock carrier. </item> - <tag><c><![CDATA[+M<S>rsbcst <ratio>]]></c></tag> - <item> <marker id="M_rsbcst"></marker> - + <tag><marker id="M_rsbcst"><c><![CDATA[+M<S>rsbcst <ratio>]]></c></marker></tag> + <item> Relative singleblock carrier shrink threshold (in percent). When a block located in an <c>mseg_alloc</c> singleblock carrier is shrunk, the carrier will be left unchanged if the ratio of unused memory is less than this threshold; otherwise, the carrier will be shrunk. See also <seealso marker="#M_asbcst">asbcst</seealso>.</item> - <tag><c><![CDATA[+M<S>sbct <size>]]></c></tag> - <item> <marker id="M_sbct"></marker> - + <tag><marker id="M_sbct"><c><![CDATA[+M<S>sbct <size>]]></c></marker></tag> + <item> Singleblock carrier threshold. Blocks larger than this threshold will be placed in singleblock carriers. Blocks smaller than this threshold will be placed in multiblock carriers.</item> - <tag><c><![CDATA[+M<S>smbcs <size>]]></c></tag> - <item> <marker id="M_smbcs"></marker> - + <tag><marker id="M_smbcs"><c><![CDATA[+M<S>smbcs <size>]]></c></marker></tag> + <item> Smallest (<c>mseg_alloc</c>) multiblock carrier size (in kilobytes). See <seealso marker="#mseg_mbc_sizes">the description on how sizes for mseg_alloc multiblock carriers are decided</seealso> in "the <c>alloc_util</c> framework" section.</item> - <tag><c><![CDATA[+M<S>t true|false|<amount>]]></c></tag> - <item> <marker id="M_t"></marker> - + <tag><marker id="M_t"><c><![CDATA[+M<S>t true|false|<amount>]]></c></marker></tag> + <item> Multiple, thread specific instances of the allocator. This option will only have any effect on the runtime system with SMP support. Default behaviour on the runtime system with @@ -451,16 +427,15 @@ <c>alloc_util</c>, i.e. all allocators based on <c>alloc_util</c> will be effected:</p> <taglist> - <tag><c><![CDATA[+Muycs <size>]]></c></tag> - <item> <marker id="Muycs"></marker> -<c>sys_alloc</c> carrier size. Carriers allocated via + <tag><marker id="Muycs"><c><![CDATA[+Muycs <size>]]></c></marker></tag> + <item> + <c>sys_alloc</c> carrier size. Carriers allocated via <c>sys_alloc</c> will be allocated in sizes which are multiples of the <c>sys_alloc</c> carrier size. This is not true for main multiblock carriers and carriers allocated during a memory shortage, though.</item> - <tag><c><![CDATA[+Mummc <amount>]]></c></tag> - <item> <marker id="Mummc"></marker> - + <tag><marker id="Mummc"><c><![CDATA[+Mummc <amount>]]></c></marker></tag> + <item> Max <c>mseg_alloc</c> carriers. Maximum number of carriers placed in separate memory segments. When this limit has been reached, new carriers will be placed in memory retrieved from @@ -468,23 +443,20 @@ </taglist> <p>Instrumentation flags:</p> <taglist> - <tag><c>+Mim true|false</c></tag> - <item> <marker id="Mim"></marker> - + <tag><marker id="Mim"><c>+Mim true|false</c></marker></tag> + <item> A map over current allocations is kept by the emulator. The allocation map can be retrieved via the <c>instrument</c> module. <c>+Mim true</c> implies <c>+Mis true</c>. <c>+Mim true</c> is the same as <seealso marker="erl#instr">-instr</seealso>.</item> - <tag><c>+Mis true|false</c></tag> - <item> <marker id="Mis"></marker> - + <tag><marker id="Mis"><c>+Mis true|false</c></marker></tag> + <item> Status over allocated memory is kept by the emulator. The allocation status can be retrieved via the <c>instrument</c> module.</item> - <tag><c>+Mit X</c></tag> - <item> <marker id="Mit"></marker> - + <tag><marker id="Mit"><c>+Mit X</c></marker></tag> + <item> Reserved for future use. Do <em>not</em> use this flag.</item> </taglist> <note> @@ -493,8 +465,8 @@ </note> <p>Other flags:</p> <taglist> - <tag><c>+Mea min|max|r9c|r10b|r11b|config</c></tag> - <item> <marker id="Mea"></marker> + <tag><marker id="Mea"><c>+Mea min|max|r9c|r10b|r11b|config</c></marker></tag> + <item> <taglist> <tag><c>min</c></tag> <item> |