From 0f54e7f02656b6634ae15870c2af272a4d8c4eac Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Tue, 5 Jul 2011 18:19:17 +0200 Subject: Update documentation with replacement of driver with nif --- lib/asn1/doc/src/asn1_spec.xmlsrc | 8 +++-- lib/asn1/doc/src/asn1_ug.xml | 48 ++++++++++++++--------------- lib/asn1/doc/src/asn1ct.xml | 29 +++++------------ lib/asn1/doc/src/asn1rt.xml | 65 +++------------------------------------ 4 files changed, 41 insertions(+), 109 deletions(-) (limited to 'lib/asn1/doc/src') diff --git a/lib/asn1/doc/src/asn1_spec.xmlsrc b/lib/asn1/doc/src/asn1_spec.xmlsrc index 8d61834da8..07cba17816 100644 --- a/lib/asn1/doc/src/asn1_spec.xmlsrc +++ b/lib/asn1/doc/src/asn1_spec.xmlsrc @@ -4,7 +4,7 @@
- 20032009 + 20032011 Ericsson AB. All Rights Reserved. @@ -43,7 +43,7 @@

So far this functionality is only provided when using the optimized BER_BIN version, that is when compiling with the options ber_bin and optimize. It does also work - using the driver option. We have no intent to make this + using the nif option. We have no intent to make this available on the default BER version, but maybe in the PER_BIN version (per_bin).

@@ -661,7 +661,9 @@ ValAction = {'Action',17,{'Button',4711,false}}.

The ASN.1 specs in the test are compiled with the options ber_bin, optimize, driver and asn1config. If the driver option had been omitted there should have been - higher values for decode and decode_part. + higher values for decode and decode_part. These tests have + not been re-run using nifs, but are expected to perform about 5% better + than the linked-in driver.

The test program runs 10000 decodes on the value, resulting in a printout with the elapsed time in microseconds for the diff --git a/lib/asn1/doc/src/asn1_ug.xml b/lib/asn1/doc/src/asn1_ug.xml index 6d9532a475..f5ff4dc2f2 100644 --- a/lib/asn1/doc/src/asn1_ug.xml +++ b/lib/asn1/doc/src/asn1_ug.xml @@ -347,7 +347,7 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn

This flag has effect only when used together with one of per_bin or ber_bin flags. It gives time optimized code in the generated modules and it uses another runtime module. - In the per_bin case a linked-in driver is used. The + In the per_bin case a nif is used. The result from an encode is a binary.

When this flag is used you cannot use the old format{TypeName,Value} when you encode values. Since it is an unnecessary construct it has been removed in favor of @@ -362,15 +362,14 @@ erlc -o ../asnfiles -I ../asnfiles -I /usr/local/standards/asn1 Person.asn +driver -

Together with the flags ber_bin and optimize - you choose to use a linked in driver for considerable faster - decode.

+

As of R15B this means the same as the nif option. Kept for + backwards compatability reasons.

+nif -

Together with the flags per_bin or ber_bin +

Together with the flags ber_bin and optimize you choose to use a nif for considerable - faster per encode and ber decode.

+ faster decode.

+asn1config @@ -498,7 +497,7 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). BER - [ber_bin, optimize, driver] + [ber_bin, optimize, nif] EAVF iolist iolist / binary @@ -563,7 +562,7 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). DER - [ber_bin, optimize, driver, der] + [ber_bin, optimize, nif, der] EAVF iolist binary @@ -632,23 +631,24 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes).

- The sole compile options ber, ber_bin and per - are kept for backwards compatibility and should not be used in - new code. + The sole compile options ber, ber_bin, per and + driver are kept for backwards compatibility and should not be + used in new code. The nif implementation which replaces the linked-in + driver has been shown to be about 5-15% faster.

You are strongly recommended to use the appropriate alternative of the bold typed options. The optimize and - driver options does not affect the encode or decode + nif options does not affect the encode or decode result, just the time spent in run-time. When ber_bin and - driver or per_bin, optimize and driver is - combined the C-code driver is used in chosen parts of encode / + nif or per_bin and optimize is + combined the C-code nif is used in chosen parts of encode / decode procedure.

Compile options, allowed combinations - use of linked-in driver + use of nif [ber] @@ -663,7 +663,7 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). no - [ber_bin, optimize, driver] + [ber_bin, optimize, nif] yes @@ -675,7 +675,7 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). no - [per_bin, optimize] + [per_bin, nif] yes @@ -696,12 +696,12 @@ asn1ct:decode('H323-MESSAGES','SomeChoiceType',Bytes). no - [ber_bin, optimize, driver, der] + [ber_bin, optimize, nif, der] yes - When the ASN1 linked-in driver is used. + When the ASN1 nif is used.
@@ -718,14 +718,14 @@ asn1rt:decode('H323-MESSAGES','SomeChoiceType',Bytes). 
 'H323-MESSAGES':encode('SomeChoiceType',{call,"octetstring"}).
 'H323-MESSAGES':decode('SomeChoiceType',Bytes).
-

The asn1 linked-in driver is enabled in two occasions: encoding of +

The asn1 nif is enabled in two occasions: encoding of asn1 values when the asn1 spec is compiled with per_bin and optimize or decode of encoded asn1 values when the asn1 spec is - compiled with ber_bin, optimize and driver. In - those cases the driver will be loaded automatically at the first call + compiled with ber_bin, optimize and nif. In + those cases the nif will be loaded automatically at the first call to encode/decode. If one doesn't want the performance - overhead of the driver being loaded at the first call it is possible - to load the driver separately by asn1rt:load_driver().

+ overhead of the nif being loaded at the first call it is possible + to load the nif separately by loading the asn1rt_nif module.

By invoking the function info/0 in a generated module, one gets information about which compiler options were used.

diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml index 2c8bef5dd8..d7c2572dc8 100644 --- a/lib/asn1/doc/src/asn1ct.xml +++ b/lib/asn1/doc/src/asn1ct.xml @@ -52,7 +52,7 @@ Options = [Option| OldOption] Option = ber_bin | per_bin | uper_bin | der | compact_bit_string | noobj | {n2n,EnumTypeName} |{outdir,Dir} | {i,IncludeDir} | optimize | - driver | asn1config | undec_rest | {inline,OutputName} | inline | + nif | asn1config | undec_rest | {inline,OutputName} | inline | {macro_name_prefix, Prefix} | {record_name_prefix, Prefix} | verbose OldOption = ber | per Reason = term() @@ -212,24 +212,21 @@ Binary = binary() per_bin or ber_bin option. It gives time optimized code generated and it uses another runtime module and - in the per_bin case a linked-in driver. The result + in the per_bin case a nif. The result in the per_bin case from an encode when compiled with this option will be a binary.

 driver -

Option valid together with ber_bin and optimize - options. It enables the use of a linked-in driver that gives - considerable faster decode. In ber_bin the driver is - enabled only by explicit use of the option driver.

+

As of R15B this means the same as the nif option. Kept for + backwards compatability reasons.

 nif

Option valid together with ber_bin and optimize - or per_bin and optimize options. It enables the - use of several nifs that gives faster decode for - ber and encode for per than the driver options gives. Nifs are - only enabled by the explicit use of the option nif

+ options. It enables the use of several nifs that gives faster + decode. Nifs are only enabled by the explicit use of the option + nif

 asn1config @@ -350,18 +347,6 @@ Binary = binary() Bytes. Returns {ok,Value} if successful.

- - validate(Module,Type,Value) -> ok | {error,Reason} - Validate an ASN.1 value. - - Module = Type = atom() - Value = term() - - -

Validates that Value conforms to Type - from Module. Not implemented in this version of the ASN.1 application.

- - value(Module ,Type) -> {ok,Value} | {error,Reason} Create an ASN.1 value for test purposes. diff --git a/lib/asn1/doc/src/asn1rt.xml b/lib/asn1/doc/src/asn1rt.xml index 1217a07e9b..0c3c257189 100644 --- a/lib/asn1/doc/src/asn1rt.xml +++ b/lib/asn1/doc/src/asn1rt.xml @@ -4,7 +4,7 @@
- 19972009 + 19972011 Ericsson AB. All Rights Reserved. @@ -41,36 +41,6 @@ - - start() -> ok |{error,Reason} - Starts the asn1 server. - - Reason = term() - - -

Starts the asn1 server that loads the drivers.

-

The server schedules a driver that is not blocked by - another caller. The driver is used by the asn1 application if - specs are compiled with options [per_bin, optimize] or - [ber_bin, optimize, driver]. The server will be started - automatically at encode/decode if it isn't done explicitly. If - encode/decode with driver is used in test or industrial code - it is a performance gain to start it explicitly to avoid the - one time load in run-time.

- - - - - stop() -> ok |{error,Reason} - Stops the asn1 server. - - Reason = term() - - -

Stops the asn1 server and unloads the drivers.

- - - decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason} Decode from bytes into an ASN.1 value. @@ -126,35 +96,23 @@ load_driver() -> ok | {error,Reason} - Loads the linked-in driver. + Loads the linked-in driver. (deprecated) Reason = term() -

This function loads the linked-in driver before the first call - to encode. If this function is not called the driver will be loaded - automatically at the first call to encode. If one doesn't want the - performance cost of a driver load when the application is running, - this function makes it possible to load the driver in an - initialization.

-

The driver is only used when encoding/decoding ASN.1 files that - were compiled with the options per_bin and optimize.

+

This function is obsolete and will be removed in R16A

 unload_driver() -> ok | {error,Reason} - Unloads the linked-in driver. + Unloads the linked-in driver. (deprecated) Reason = term() -

This function unloads the linked-in driver. - When the driver has been loaded it remains in the environment until - it is unloaded. Normally the driver should remain loaded, it is - crucial for the performance of ASN.1 encoding.

-

The driver is only used when ASN.1 modules have been compiled - with the flags per_bin and optimize.

+

This function is obsolete and will be removed in R16A

 @@ -188,19 +146,6 @@ value, to a UTF8 encoded binary.

 - - - validate(Module,Type,Value) -> ok | {error,Reason} - Validate an ASN.1 value. - - Module = Type = atom() - Value = term() - - -

Validates that Value conforms to Type - from Module. Not implemented in this version of the ASN.1 application.

- - -- cgit v1.2.3