Mercurial > hg > nginx-site

comparison xml/en/docs/dev/development_guide.xml @ 2412:bd026d5898b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Minor language improvements in Development guide.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 30 Jul 2019 19:38:09 +0300
parents 392e11db3260
children eca8e37a34ef
comparison
equal deleted inserted replaced
2411:7202f078bfa7 2412:bd026d5898b8
7269 <section name="Common Pitfalls" id="common_pitfals"> 7269 <section name="Common Pitfalls" id="common_pitfals">
7270 7270
7271 <section name="Writing a C module" id="module_pitfall"> 7271 <section name="Writing a C module" id="module_pitfall">
7272 7272
7273 <para> 7273 <para>
7274 The most common pitfall is an attempt to write a full-fledged C module. 7274 The most common pitfall is an attempt to write a full-fledged C module
7275 when it can be avoided.
7275 In most cases your task can be accomplished by creating a proper configuration. 7276 In most cases your task can be accomplished by creating a proper configuration.
7276 If writing a module is inevitable, try to make it 7277 If writing a module is inevitable, try to make it
7277 as small and simple as possible. 7278 as small and simple as possible.
7278 For example, a module can only export some 7279 For example, a module can only export some
7279 <link id="http_variables">variables</link>. 7280 <link id="http_variables">variables</link>.
7308 <link id="string_overview">ngx_str_t</link> is not a C-Style 7309 <link id="string_overview">ngx_str_t</link> is not a C-Style
7309 zero-terminated string. 7310 zero-terminated string.
7310 You cannot pass the data to standard C library functions 7311 You cannot pass the data to standard C library functions
7311 such as <c-func>strlen</c-func> or <c-func>strstr</c-func>. 7312 such as <c-func>strlen</c-func> or <c-func>strstr</c-func>.
7312 Instead, nginx <link id="string_overview">counterparts</link> 7313 Instead, nginx <link id="string_overview">counterparts</link>
7313 should be used that accept either <literal>ngx_str_t</literal> 7314 that accept either <literal>ngx_str_t</literal> should be used
7314 or pointer to data and a length. 7315 or pointer to data and a length.
7315 However, there is a case when <literal>ngx_str_t</literal> holds 7316 However, there is a case when <literal>ngx_str_t</literal> holds
7316 a pointer to a zero-terminated string: strings that come as a result of 7317 a pointer to a zero-terminated string: strings that come as a result of
7317 configuration file parsing are zero-terminated. 7318 configuration file parsing are zero-terminated.
7318 </para> 7319 </para>
7327 Any global data should be tied to a <link id="cycle">configuration cycle</link> 7328 Any global data should be tied to a <link id="cycle">configuration cycle</link>
7328 and be allocated from the corresponding <link id="pool">memory pool</link>. 7329 and be allocated from the corresponding <link id="pool">memory pool</link>.
7329 This allows nginx to perform graceful configuration reloads. 7330 This allows nginx to perform graceful configuration reloads.
7330 An attempt to use global variables will likely break this feature, 7331 An attempt to use global variables will likely break this feature,
7331 because it will be impossible to have two configurations at 7332 because it will be impossible to have two configurations at
7332 the same time and abandon of them. 7333 the same time and get rid of them.
7333 Sometimes global variables are required. 7334 Sometimes global variables are required.
7334 In this case, special attention is needed to manage reconfiguration 7335 In this case, special attention is needed to manage reconfiguration
7335 properly. 7336 properly.
7336 Also, check if libraries used by your code have implicit 7337 Also, check if libraries used by your code have implicit
7337 global state that may be broken on reload. 7338 global state that may be broken on reload.
7342 <section name="Manual Memory Management" id="manual_memory_management"> 7343 <section name="Manual Memory Management" id="manual_memory_management">
7343 7344
7344 <para> 7345 <para>
7345 Instead of dealing with malloc/free approach which is error prone, 7346 Instead of dealing with malloc/free approach which is error prone,
7346 learn how to use nginx <link id="pool">pools</link>. 7347 learn how to use nginx <link id="pool">pools</link>.
7347 A pool is created and tied to some object - 7348 A pool is created and tied to an object -
7348 <link id="http_conf">configuration</link>, 7349 <link id="http_conf">configuration</link>,
7349 <link id="cycle">cycle</link>, 7350 <link id="cycle">cycle</link>,
7350 <link id="connection">connection</link>, 7351 <link id="connection">connection</link>,
7351 or <link id="http_request">HTTP request</link>. 7352 or <link id="http_request">HTTP request</link>.
7352 When an object is destroyed, the associated pool is destroyed too. 7353 When the object is destroyed, the associated pool is destroyed too.
7353 So when working with an object, it is possible to allocate as much as 7354 So when working with an object, it is possible to allocate the amount
7354 needed from the corresponding pool and don't care about freeing memory, 7355 needed from the corresponding pool and don't care about freeing memory
7355 even in case of errors. 7356 even in case of errors.
7356 </para> 7357 </para>
7357 7358
7358 </section> 7359 </section>
7359 7360
7378 7379
7379 <para> 7380 <para>
7380 A common mistake is to use libraries that are blocking internally. 7381 A common mistake is to use libraries that are blocking internally.
7381 Most libraries out there are synchronous and blocking by nature. 7382 Most libraries out there are synchronous and blocking by nature.
7382 In other words, they perform one operation at a time and waste 7383 In other words, they perform one operation at a time and waste
7383 time waiting response from other peer. 7384 time waiting for response from other peer.
7384 As a result, when a request is processed with such library, whole 7385 As a result, when a request is processed with such library, whole
7385 nginx worker is blocked, thus destroying performance. 7386 nginx worker is blocked, thus destroying performance.
7386 Use only libraries that provide asynchronous interface and don't 7387 Use only libraries that provide asynchronous interface and don't
7387 block whole process. 7388 block whole process.
7388 </para> 7389 </para>
7393 <section name="HTTP Requests to External Services" id="http_requests_to_ext"> 7394 <section name="HTTP Requests to External Services" id="http_requests_to_ext">
7394 7395
7395 <para> 7396 <para>
7396 Often modules need to perform an HTTP call to some external service. 7397 Often modules need to perform an HTTP call to some external service.
7397 A common mistake is to use some external library, such as libcurl, 7398 A common mistake is to use some external library, such as libcurl,
7398 to perform HTTP request. 7399 to perform the HTTP request.
7399 It is absolutely unnecessary to bring a huge amount of external 7400 It is absolutely unnecessary to bring a huge amount of external
7400 (probably <link id="using_libraries">blocking</link>!) code 7401 (probably <link id="using_libraries">blocking</link>!) code
7401 for the task which can be accomplished by nginx itself. 7402 for the task which can be accomplished by nginx itself.
7402 </para> 7403 </para>
7403 7404